From d03956031697597efed8b6819f5becb7270bace8 Mon Sep 17 00:00:00 2001 From: Congyi Wu Date: Thu, 16 Sep 2021 17:52:35 -0400 Subject: [PATCH] Bump required vscode version to 1.60.1 It looks like enableProposedApi was previously required for `workspaces.notebookDocuments`, which were finallized in these commits released in 1.60.1: * e1928efb notebook API finalization part1 * ac05ae7b move file'ish things into workspace namespace --- .vscode/launch.json | 3 +- README.md | 6 +- package-lock.json | 2 +- package.json | 4 +- vscode.d.ts | 1253 +++++++++++++++++++++++++++++++++------ vscode.proposed.d.ts | 1319 ++++++++++++++++++++---------------------- 6 files changed, 1684 insertions(+), 903 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index b5cbc13..6f9097a 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -10,8 +10,7 @@ "type": "extensionHost", "request": "launch", "args": [ - "--extensionDevelopmentPath=${workspaceFolder}", - "--enable-proposed-api" + "--extensionDevelopmentPath=${workspaceFolder}" ], "outFiles": [ "${workspaceFolder}/dist/**/*.js" diff --git a/README.md b/README.md index abc5c40..cae05ea 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,8 @@ A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marke * Python (temporary, see `Roadmap`) # Getting Started -* Please install VS Code Insiders (stable is not yet supported) -* Install this extension -* Launch VS Code with the following command line `code-insiders --enable-proposed-api=donjayamanne.vscode-jupytext` -* Right click a file and select `Open as a Jupyter Notebook` +* This extension requires VS Code 1.60.1 or newer +* Right click a `*.py` file and select `Open as a Jupyter Notebook` * Start executing code against Jupyter Kernels, save changes to notebook will result in the corresponding script file getting updated. diff --git a/package-lock.json b/package-lock.json index be4e890..22eeee5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -31,7 +31,7 @@ "webpack-cli": "^4.4.0" }, "engines": { - "vscode": "1.57.0-insider" + "vscode": "^1.60.1" } }, "node_modules/@babel/code-frame": { diff --git a/package.json b/package.json index cec847b..0016ff1 100644 --- a/package.json +++ b/package.json @@ -4,10 +4,10 @@ "description": "Open, edit and execute plain script files (Python, R, Julia, TypeScript, C#, etc) as Jupyter Notebooks", "publisher": "donjayamanne", "version": "0.1.0", - "enableProposedApi": true, + "enableProposedApi": false, "preview": true, "engines": { - "vscode": "1.57.0-insider" + "vscode": "^1.60.1" }, "license": "BSD-3-Clause", "icon": "icon.png", diff --git a/vscode.d.ts b/vscode.d.ts index 83e8531..6e883e8 100644 --- a/vscode.d.ts +++ b/vscode.d.ts @@ -106,7 +106,7 @@ declare module 'vscode' { /** * Is this document representing an untitled file which has never been saved yet. *Note* that - * this does not mean the document will be saved to disk, use {@link Uri.scheme `uri.scheme`} + * this does not mean the document will be saved to disk, use {@linkcode Uri.scheme} * to figure out where a document will be {@link FileSystemProvider saved}, e.g. `file`, `ftp` etc. */ readonly isUntitled: boolean; @@ -214,7 +214,7 @@ declare module 'vscode' { * if it does, it will be ignored. * * *Note 2:* A custom regular expression will fail to match multiline strings * and in the name of speed regular expressions should not match words with - * spaces. Use {@link TextLine.text `TextLine.text`} for more complex, non-wordy, scenarios. + * spaces. Use {@linkcode TextLine.text} for more complex, non-wordy, scenarios. * * The position will be {@link TextDocument.validatePosition adjusted}. * @@ -502,7 +502,7 @@ declare module 'vscode' { constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number); /** - * A selection is reversed if {@link Selection.active active}.isBefore({@link Selection.anchor anchor}). + * A selection is reversed if its {@link Selection.anchor anchor} is the {@link Selection.end end} position. */ isReversed: boolean; } @@ -755,7 +755,7 @@ declare module 'vscode' { * An optional view column in which the {@link TextEditor editor} should be shown. * The default is the {@link ViewColumn.Active active}, other values are adjusted to * be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is - * not adjusted. Use {@link ViewColumn.Beside `ViewColumn.Beside`} to open the + * not adjusted. Use {@linkcode ViewColumn.Beside} to open the * editor to the side of the currently active one. */ viewColumn?: ViewColumn; @@ -1055,7 +1055,7 @@ declare module 'vscode' { /** * A message that should be rendered when hovering over the decoration. */ - hoverMessage?: MarkedString | MarkedString[]; + hoverMessage?: MarkdownString | MarkedString | Array; /** * Render options applied to the current decoration. For performance reasons, keep the @@ -1366,7 +1366,7 @@ declare module 'vscode' { * * The resulting string shall *not* be used for display purposes but * for disk operations, like `readFile` et al. * - * The *difference* to the {@link Uri.path `path`}-property is the use of the platform specific + * The *difference* to the {@linkcode Uri.path path}-property is the use of the platform specific * path separator and the handling of UNC paths. The sample below outlines the difference: * ```ts const u = URI.parse('file://server/c$/folder/file.txt') @@ -1700,6 +1700,7 @@ declare module 'vscode' { /** * Set to `true` to keep the picker open when focus moves to another part of the editor or to another window. + * This setting is ignored on iPad and is always false. */ ignoreFocusOut?: boolean; @@ -1726,6 +1727,7 @@ declare module 'vscode' { /** * Set to `true` to keep the picker open when focus moves to another part of the editor or to another window. + * This setting is ignored on iPad and is always false. */ ignoreFocusOut?: boolean; } @@ -1858,6 +1860,12 @@ declare module 'vscode' { * Indicates that this message should be modal. */ modal?: boolean; + + /** + * Human-readable detail message that is rendered less prominent. _Note_ that detail + * is only shown for {@link MessageOptions.modal modal} messages. + */ + detail?: string; } /** @@ -1876,7 +1884,7 @@ declare module 'vscode' { value?: string; /** - * Selection of the prefilled {@link InputBoxOptions.value `value`}. Defined as tuple of two number where the + * Selection of the prefilled {@linkcode InputBoxOptions.value value}. Defined as tuple of two number where the * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole * word will be selected, when empty (start equals end) only the cursor will be set, * otherwise the defined range will be selected. @@ -1900,6 +1908,7 @@ declare module 'vscode' { /** * Set to `true` to keep the input box open when focus moves to another part of the editor or to another window. + * This setting is ignored on iPad and is always false. */ ignoreFocusOut?: boolean; @@ -1989,7 +1998,7 @@ declare module 'vscode' { * { language: 'typescript', scheme: 'file' } * * @example A language filter that applies to all package.json paths - * { language: 'json', scheme: 'untitled', pattern: '**​/package.json' } + * { language: 'json', pattern: '**​/package.json' } */ export interface DocumentFilter { @@ -2025,12 +2034,12 @@ declare module 'vscode' { export type DocumentSelector = DocumentFilter | string | ReadonlyArray; /** - * A provider result represents the values a provider, like the {@link HoverProvider `HoverProvider`}, + * A provider result represents the values a provider, like the {@linkcode HoverProvider}, * may return. For once this is the actual result type `T`, like `Hover`, or a thenable that resolves * to that type `T`. In addition, `null` and `undefined` can be returned - either directly or from a * thenable. * - * The snippets below are all valid implementations of the {@link HoverProvider `HoverProvider`}: + * The snippets below are all valid implementations of the {@linkcode HoverProvider}: * * ```ts * let a: HoverProvider = { @@ -2225,7 +2234,7 @@ declare module 'vscode' { * A code action represents a change that can be performed in code, e.g. to fix a problem or * to refactor code. * - * A CodeAction must set either {@link CodeAction.edit `edit`} and/or a {@link CodeAction.command `command`}. If both are supplied, the `edit` is applied first, then the command is executed. + * A CodeAction must set either {@linkcode CodeAction.edit edit} and/or a {@linkcode CodeAction.command command}. If both are supplied, the `edit` is applied first, then the command is executed. */ export class CodeAction { @@ -2327,7 +2336,7 @@ declare module 'vscode' { provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | T)[]>; /** - * Given a code action fill in its {@link CodeAction.edit `edit`}-property. Changes to + * Given a code action fill in its {@linkcode CodeAction.edit edit}-property. Changes to * all other properties, like title, are ignored. A code action that has an edit * will not be resolved. * @@ -2384,9 +2393,9 @@ declare module 'vscode' { /** * Command that displays the documentation to the user. * - * This can display the documentation directly in the editor or open a website using {@link env.openExternal `env.openExternal`}; + * This can display the documentation directly in the editor or open a website using {@linkcode env.openExternal}; * - * The title of this documentation code action is taken from {@link Command.title `Command.title`} + * The title of this documentation code action is taken from {@linkcode Command.title} */ readonly command: Command; }>; @@ -2560,8 +2569,8 @@ declare module 'vscode' { * The MarkdownString represents human-readable text that supports formatting via the * markdown syntax. Standard markdown is supported, also tables, but no embedded html. * - * When created with `supportThemeIcons` then rendering of {@link ThemeIcon theme icons} via - * the `$()`-syntax is supported. + * Rendering of {@link ThemeIcon theme icons} via the `$()`-syntax is supported + * when the {@linkcode MarkdownString.supportThemeIcons supportThemeIcons} is set to `true`. */ export class MarkdownString { @@ -2579,13 +2588,13 @@ declare module 'vscode' { /** * Indicates that this markdown string can contain {@link ThemeIcon ThemeIcons}, e.g. `$(zap)`. */ - readonly supportThemeIcons?: boolean; + supportThemeIcons?: boolean; /** * Creates a new markdown string with the given value. * * @param value Optional, initial value. - * @param supportThemeIcons Optional, Specifies whether {@link ThemeIcon ThemeIcons} are supported within the {@link MarkdownString `MarkdownString`}. + * @param supportThemeIcons Optional, Specifies whether {@link ThemeIcon ThemeIcons} are supported within the {@linkcode MarkdownString}. */ constructor(value?: string, supportThemeIcons?: boolean); @@ -2596,7 +2605,7 @@ declare module 'vscode' { appendText(value: string): MarkdownString; /** - * Appends the given string 'as is' to this markdown string. When {@link MarkdownString.supportThemeIcons `supportThemeIcons`} is `true`, {@link ThemeIcon ThemeIcons} in the `value` will be iconified. + * Appends the given string 'as is' to this markdown string. When {@linkcode MarkdownString.supportThemeIcons supportThemeIcons} is `true`, {@link ThemeIcon ThemeIcons} in the `value` will be iconified. * @param value Markdown string. */ appendMarkdown(value: string): MarkdownString; @@ -2614,9 +2623,9 @@ declare module 'vscode' { * or a code-block that provides a language and a code snippet. Note that * markdown strings will be sanitized - that means html will be escaped. * - * @deprecated This type is deprecated, please use {@link MarkdownString `MarkdownString`} instead. + * @deprecated This type is deprecated, please use {@linkcode MarkdownString} instead. */ - export type MarkedString = MarkdownString | string | { language: string; value: string }; + export type MarkedString = string | { language: string; value: string }; /** * A hover represents additional information for a symbol or word. Hovers are @@ -2627,7 +2636,7 @@ declare module 'vscode' { /** * The contents of this hover. */ - contents: MarkedString[]; + contents: Array; /** * The range to which this hover applies. When missing, the @@ -2642,7 +2651,7 @@ declare module 'vscode' { * @param contents The contents of the hover. * @param range The range to which the hover applies. */ - constructor(contents: MarkedString | MarkedString[], range?: Range); + constructor(contents: MarkdownString | MarkedString | Array, range?: Range); } /** @@ -3040,7 +3049,7 @@ declare module 'vscode' { /** * The range that should be selected and reveal when this symbol is being picked, e.g. the name of a function. - * Must be contained by the {@link DocumentSymbol.range `range`}. + * Must be contained by the {@linkcode DocumentSymbol.range range}. */ selectionRange: Range; @@ -3116,7 +3125,7 @@ declare module 'vscode' { /** * Given a symbol fill in its {@link SymbolInformation.location location}. This method is called whenever a symbol * is selected in the UI. Providers can implement this method and return incomplete symbols from - * {@link WorkspaceSymbolProvider.provideWorkspaceSymbols `provideWorkspaceSymbols`} which often helps to improve + * {@linkcode WorkspaceSymbolProvider.provideWorkspaceSymbols provideWorkspaceSymbols} which often helps to improve * performance. * * @param symbol The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an @@ -3380,7 +3389,7 @@ declare module 'vscode' { /** * Builder-function that appends the given string to - * the {@link SnippetString.value `value`} of this snippet string. + * the {@linkcode SnippetString.value value} of this snippet string. * * @param string A value to append 'as given'. The string will be escaped. * @return This snippet string. @@ -3389,7 +3398,7 @@ declare module 'vscode' { /** * Builder-function that appends a tabstop (`$1`, `$2` etc) to - * the {@link SnippetString.value `value`} of this snippet string. + * the {@linkcode SnippetString.value value} of this snippet string. * * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. @@ -3399,7 +3408,7 @@ declare module 'vscode' { /** * Builder-function that appends a placeholder (`${1:value}`) to - * the {@link SnippetString.value `value`} of this snippet string. + * the {@linkcode SnippetString.value value} of this snippet string. * * @param value The value of this placeholder - either a string or a function * with which a nested snippet can be created. @@ -3411,7 +3420,7 @@ declare module 'vscode' { /** * Builder-function that appends a choice (`${1|a,b,c|}`) to - * the {@link SnippetString.value `value`} of this snippet string. + * the {@linkcode SnippetString.value value} of this snippet string. * * @param values The values for choices - the array of strings * @param number The number of this tabstop, defaults to an auto-increment @@ -3422,7 +3431,7 @@ declare module 'vscode' { /** * Builder-function that appends a variable (`${VAR}`) to - * the {@link SnippetString.value `value`} of this snippet string. + * the {@linkcode SnippetString.value value} of this snippet string. * * @param name The name of the variable - excluding the `$`. * @param defaultValue The default value which is used when the variable name cannot @@ -3837,7 +3846,7 @@ declare module 'vscode' { /** * The index of the active parameter. * - * If provided, this is used in place of {@link SignatureHelp.activeSignature `SignatureHelp.activeSignature`}. + * If provided, this is used in place of {@linkcode SignatureHelp.activeSignature}. */ activeParameter?: number; @@ -3874,7 +3883,7 @@ declare module 'vscode' { } /** - * How a {@link SignatureHelpProvider `SignatureHelpProvider`} was triggered. + * How a {@linkcode SignatureHelpProvider} was triggered. */ export enum SignatureHelpTriggerKind { /** @@ -3895,7 +3904,7 @@ declare module 'vscode' { /** * Additional information about the context in which a - * {@link SignatureHelpProvider.provideSignatureHelp `SignatureHelpProvider`} was triggered. + * {@linkcode SignatureHelpProvider.provideSignatureHelp SignatureHelpProvider} was triggered. */ export interface SignatureHelpContext { /** @@ -3920,7 +3929,7 @@ declare module 'vscode' { readonly isRetrigger: boolean; /** - * The currently active {@link SignatureHelp `SignatureHelp`}. + * The currently active {@linkcode SignatureHelp}. * * The `activeSignatureHelp` has its [`SignatureHelp.activeSignature`] field updated based on * the user arrowing through available signatures. @@ -3949,7 +3958,7 @@ declare module 'vscode' { } /** - * Metadata about a registered {@link SignatureHelpProvider `SignatureHelpProvider`}. + * Metadata about a registered {@linkcode SignatureHelpProvider}. */ export interface SignatureHelpProviderMetadata { /** @@ -3966,6 +3975,31 @@ declare module 'vscode' { readonly retriggerCharacters: readonly string[]; } + /** + * A structured label for a {@link CompletionItem completion item}. + */ + export interface CompletionItemLabel { + + /** + * The label of this completion item. + * + * By default this is also the text that is inserted when this completion is selected. + */ + label: string; + + /** + * An optional string which is rendered less prominently directly after {@link CompletionItemLabel.label label}, + * without any spacing. Should be used for function signatures or type annotations. + */ + detail?: string; + + /** + * An optional string which is rendered less prominently after {@link CompletionItemLabel.detail}. Should be used + * for fully qualified names or file path. + */ + description?: string; + } + /** * Completion item kinds. */ @@ -4032,7 +4066,7 @@ declare module 'vscode' { * this is also the text that is inserted when selecting * this completion. */ - label: string; + label: string | CompletionItemLabel; /** * The kind of this completion item. Based on the kind @@ -4065,7 +4099,7 @@ declare module 'vscode' { * items. When having a leading word (prefix) ordering is based on how * well completions match that prefix and the initial ordering is only used * when completions match equally well. The prefix is defined by the - * {@link CompletionItem.range `range`}-property and can therefore be different + * {@linkcode CompletionItem.range range}-property and can therefore be different * for each completion. */ sortText?: string; @@ -4076,7 +4110,7 @@ declare module 'vscode' { * is used. * * Note that the filter text is matched against the leading word (prefix) which is defined - * by the {@link CompletionItem.range `range`}-property. + * by the {@linkcode CompletionItem.range range}-property. */ filterText?: string; @@ -4156,7 +4190,7 @@ declare module 'vscode' { * @param label The label of the completion. * @param kind The {@link CompletionItemKind kind} of the completion. */ - constructor(label: string, kind?: CompletionItemKind); + constructor(label: string | CompletionItemLabel, kind?: CompletionItemKind); } /** @@ -4227,9 +4261,9 @@ declare module 'vscode' { * The completion item provider interface defines the contract between extensions and * [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense). * - * Providers can delay the computation of the {@link CompletionItem.detail `detail`} - * and {@link CompletionItem.documentation `documentation`} properties by implementing the - * {@link CompletionItemProvider.resolveCompletionItem `resolveCompletionItem`}-function. However, properties that + * Providers can delay the computation of the {@linkcode CompletionItem.detail detail} + * and {@linkcode CompletionItem.documentation documentation} properties by implementing the + * {@linkcode CompletionItemProvider.resolveCompletionItem resolveCompletionItem}-function. However, properties that * are needed for the initial sorting and filtering, like `sortText`, `filterText`, `insertText`, and `range`, must * not be changed during resolve. * @@ -4327,7 +4361,7 @@ declare module 'vscode' { /** * Given a link fill in its {@link DocumentLink.target target}. This method is called when an incomplete * link is selected in the UI. Providers can implement this method and return incomplete links - * (without target) from the {@link DocumentLinkProvider.provideDocumentLinks `provideDocumentLinks`} method which + * (without target) from the {@linkcode DocumentLinkProvider.provideDocumentLinks provideDocumentLinks} method which * often helps to improve performance. * * @param link The link that is to be resolved. @@ -4398,7 +4432,7 @@ declare module 'vscode' { } /** - * A color presentation object describes how a {@link Color `color`} should be represented as text and what + * A color presentation object describes how a {@linkcode Color} should be represented as text and what * edits are required to refer to it from source code. * * For some languages one color can have multiple presentations, e.g. css can represent the color red with @@ -4627,7 +4661,7 @@ declare module 'vscode' { /** * The range that should be selected and revealed when this symbol is being picked, e.g. the name of a function. - * Must be contained by the {@link CallHierarchyItem.range `range`}. + * Must be contained by the {@linkcode CallHierarchyItem.range range}. */ selectionRange: Range; @@ -4649,7 +4683,7 @@ declare module 'vscode' { /** * The range at which at which the calls appears. This is relative to the caller - * denoted by {@link CallHierarchyIncomingCall.from `this.from`}. + * denoted by {@linkcode CallHierarchyIncomingCall.from this.from}. */ fromRanges: Range[]; @@ -4674,8 +4708,8 @@ declare module 'vscode' { /** * The range at which this item is called. This is the range relative to the caller, e.g the item - * passed to {@link CallHierarchyProvider.provideCallHierarchyOutgoingCalls `provideCallHierarchyOutgoingCalls`} - * and not {@link CallHierarchyOutgoingCall.to `this.to`}. + * passed to {@linkcode CallHierarchyProvider.provideCallHierarchyOutgoingCalls provideCallHierarchyOutgoingCalls} + * and not {@linkcode CallHierarchyOutgoingCall.to this.to}. */ fromRanges: Range[]; @@ -4703,8 +4737,8 @@ declare module 'vscode' { * @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 A call hierarchy item or a thenable that resolves to such. The lack of a result can be - * signaled by returning `undefined` or `null`. + * @returns One or multiple call 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. */ prepareCallHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult; @@ -4733,6 +4767,104 @@ declare module 'vscode' { provideCallHierarchyOutgoingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult; } + /** + * 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 direct 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 direct 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; + } + /** * Represents a list of ranges that can be edited together along with a word pattern to describe valid range contents. */ @@ -4985,7 +5117,7 @@ declare module 'vscode' { * - *Workspace Folder settings* - From one of the {@link workspace.workspaceFolders Workspace Folders} under which requested resource belongs to. * - *Language settings* - Settings defined under requested language. * - * The *effective* value (returned by {@link WorkspaceConfiguration.get `get`}) is computed by overriding or merging the values in the following order. + * The *effective* value (returned by {@linkcode WorkspaceConfiguration.get get}) is computed by overriding or merging the values in the following order. * * ``` * `defaultValue` (if defined in `package.json` otherwise derived from the value's type) @@ -5127,7 +5259,7 @@ declare module 'vscode' { * - configuration to workspace folder when there is no workspace folder settings. * - configuration to workspace folder when {@link WorkspaceConfiguration} is not scoped to a resource. */ - update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable; + update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean | null, overrideInLanguage?: boolean): Thenable; /** * Readable dictionary that backs this configuration. @@ -5587,7 +5719,7 @@ declare module 'vscode' { /** * The identifier of this item. * - * *Note*: if no identifier was provided by the {@link window.createStatusBarItem `window.createStatusBarItem`} + * *Note*: if no identifier was provided by the {@linkcode window.createStatusBarItem} * method, the identifier will match the {@link Extension.id extension identifier}. */ readonly id: string; @@ -5623,7 +5755,7 @@ declare module 'vscode' { /** * The tooltip text when you hover over this entry. */ - tooltip: string | undefined; + tooltip: string | MarkdownString | undefined; /** * The foreground color for this entry. @@ -5633,9 +5765,11 @@ declare module 'vscode' { /** * The background color for this entry. * - * *Note*: only `new ThemeColor('statusBarItem.errorBackground')` is - * supported for now. More background colors may be supported in the - * future. + * *Note*: only the following colors are supported: + * * `new ThemeColor('statusBarItem.errorBackground')` + * * `new ThemeColor('statusBarItem.warningBackground')` + * + * More background colors may be supported in the future. * * *Note*: when a background color is set, the statusbar may override * the `color` choice to ensure the entry is readable in all themes. @@ -5643,11 +5777,11 @@ declare module 'vscode' { backgroundColor: ThemeColor | undefined; /** - * {@link Command `Command`} or identifier of a command to run on click. + * {@linkcode Command} or identifier of a command to run on click. * * The command must be {@link commands.getCommands known}. * - * Note that if this is a {@link Command `Command`} object, only the {@link Command.command `command`} and {@link Command.arguments `arguments`} + * Note that if this is a {@linkcode Command} object, only the {@linkcode Command.command command} and {@linkcode Command.arguments arguments} * are used by the editor. */ command: string | Command | undefined; @@ -5792,7 +5926,7 @@ declare module 'vscode' { /** * A link on a terminal line. */ - export interface TerminalLink { + export class TerminalLink { /** * The start index of the link on {@link TerminalLinkContext.line}. */ @@ -5811,6 +5945,47 @@ declare module 'vscode' { * depending on OS, user settings, and localization. */ tooltip?: string; + + /** + * Creates a new terminal link. + * @param startIndex The start index of the link on {@link TerminalLinkContext.line}. + * @param length The length of the link on {@link TerminalLinkContext.line}. + * @param tooltip The tooltip text when you hover over this link. + * + * If a tooltip is provided, is will be displayed in a string that includes instructions on + * how to trigger the link, such as `{0} (ctrl + click)`. The specific instructions vary + * depending on OS, user settings, and localization. + */ + constructor(startIndex: number, length: number, tooltip?: string); + } + + /** + * Provides a terminal profile for the contributed terminal profile when launched via the UI or + * command. + */ + export interface TerminalProfileProvider { + /** + * Provide the terminal profile. + * @param token A cancellation token that indicates the result is no longer needed. + * @returns The terminal profile. + */ + provideTerminalProfile(token: CancellationToken): ProviderResult; + } + + /** + * A terminal profile defines how a terminal will be launched. + */ + export class TerminalProfile { + /** + * The options that the terminal will launch with. + */ + options: TerminalOptions | ExtensionTerminalOptions; + + /** + * Creates a new terminal profile. + * @param options The options that the terminal will launch with. + */ + constructor(options: TerminalOptions | ExtensionTerminalOptions); } /** @@ -5934,7 +6109,7 @@ declare module 'vscode' { * or if an extension runs where the remote extension host runs. The extension kind * is defined in the `package.json`-file of extensions but can also be refined * via the `remote.extensionKind`-setting. When no remote extension host exists, - * the value is {@link ExtensionKind.UI `ExtensionKind.UI`}. + * the value is {@linkcode ExtensionKind.UI}. */ extensionKind: ExtensionKind; @@ -6044,8 +6219,8 @@ declare module 'vscode' { /** * Get the absolute path of a resource contained in the extension. * - * *Note* that an absolute uri can be constructed via {@link Uri.joinPath `Uri.joinPath`} and - * {@link ExtensionContext.extensionUri `extensionUri`}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);` + * *Note* that an absolute uri can be constructed via {@linkcode Uri.joinPath} and + * {@linkcode ExtensionContext.extensionUri extensionUri}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);` * * @param relativePath A relative path to a resource contained in the extension. * @return The absolute path of the resource. @@ -6058,10 +6233,10 @@ declare module 'vscode' { * up to the extension. However, the parent directory is guaranteed to be existent. * The value is `undefined` when no workspace nor folder has been opened. * - * Use {@link ExtensionContext.workspaceState `workspaceState`} or - * {@link ExtensionContext.globalState `globalState`} to store key value data. + * Use {@linkcode ExtensionContext.workspaceState workspaceState} or + * {@linkcode ExtensionContext.globalState globalState} to store key value data. * - * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from + * @see {@linkcode FileSystem workspace.fs} for how to read and write files and folders from * an uri. */ readonly storageUri: Uri | undefined; @@ -6071,8 +6246,8 @@ declare module 'vscode' { * can store private state. The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * - * Use {@link ExtensionContext.workspaceState `workspaceState`} or - * {@link ExtensionContext.globalState `globalState`} to store key value data. + * Use {@linkcode ExtensionContext.workspaceState workspaceState} or + * {@linkcode ExtensionContext.globalState globalState} to store key value data. * * @deprecated Use {@link ExtensionContext.storageUri storageUri} instead. */ @@ -6083,9 +6258,9 @@ declare module 'vscode' { * The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * - * Use {@link ExtensionContext.globalState `globalState`} to store key value data. + * Use {@linkcode ExtensionContext.globalState globalState} to store key value data. * - * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from + * @see {@linkcode FileSystem workspace.fs} for how to read and write files and folders from * an uri. */ readonly globalStorageUri: Uri; @@ -6095,7 +6270,7 @@ declare module 'vscode' { * The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * - * Use {@link ExtensionContext.globalState `globalState`} to store key value data. + * Use {@linkcode ExtensionContext.globalState globalState} to store key value data. * * @deprecated Use {@link ExtensionContext.globalStorageUri globalStorageUri} instead. */ @@ -6106,7 +6281,7 @@ declare module 'vscode' { * The directory might not exist on disk and creation is up to the extension. However, * the parent directory is guaranteed to be existent. * - * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from + * @see {@linkcode FileSystem workspace.fs} for how to read and write files and folders from * an uri. */ readonly logUri: Uri; @@ -6139,6 +6314,13 @@ declare module 'vscode' { */ export interface Memento { + /** + * Returns the stored keys. + * + * @return The stored keys. + */ + keys(): readonly string[]; + /** * Return a value. * @@ -6336,6 +6518,17 @@ declare module 'vscode' { */ static Test: TaskGroup; + /** + * Whether the task that is part of this group is the default for the group. + * This property cannot be set through API, and is controlled by a user's task configurations. + */ + readonly isDefault?: boolean; + + /** + * The ID of the task group. Is one of TaskGroup.Clean.id, TaskGroup.Build.id, TaskGroup.Rebuild.id, or TaskGroup.Test.id. + */ + readonly id: string; + private constructor(id: string, label: string); } @@ -6733,7 +6926,7 @@ declare module 'vscode' { provideTasks(token: CancellationToken): ProviderResult; /** - * Resolves a task that has no {@link Task.execution `execution`} set. Tasks are + * Resolves a task that has no {@linkcode Task.execution execution} set. Tasks are * often created from information found in the `tasks.json`-file. Such tasks miss * the information on how to execute them and a task provider must fill in * the missing information in the `resolveTask`-method. This method will not be @@ -6930,6 +7123,18 @@ declare module 'vscode' { SymbolicLink = 64 } + export enum FilePermission { + /** + * The file is readonly. + * + * *Note:* All `FileStat` from a `FileSystemProvider` that is registered with + * the option `isReadonly: true` will be implicitly handled as if `FilePermission.Readonly` + * is set. As a consequence, it is not possible to have a readonly file system provider + * registered where some `FileStat` are not readonly. + */ + Readonly = 1 + } + /** * The `FileStat`-type represents metadata about a file */ @@ -6961,6 +7166,12 @@ declare module 'vscode' { * example. */ size: number; + /** + * The permissions of the file, e.g. whether the file is readonly. + * + * *Note:* This value might be a bitmask, e.g. `FilePermission.Readonly | FilePermission.Other`. + */ + permissions?: FilePermission; } /** @@ -7019,7 +7230,7 @@ declare module 'vscode' { /** * A code that identifies this error. * - * Possible values are names of errors, like {@link FileSystemError.FileNotFound `FileNotFound`}, + * Possible values are names of errors, like {@linkcode FileSystemError.FileNotFound FileNotFound}, * or `Unknown` for unspecified errors. */ readonly code: string; @@ -7110,7 +7321,7 @@ declare module 'vscode' { * * @param uri The uri of the file to retrieve metadata about. * @return The file metadata about the file. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. */ stat(uri: Uri): FileStat | Thenable; @@ -7119,7 +7330,7 @@ declare module 'vscode' { * * @param uri The uri of the folder. * @return An array of name/type-tuples or a thenable that resolves to such. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. */ readDirectory(uri: Uri): [string, FileType][] | Thenable<[string, FileType][]>; @@ -7127,9 +7338,9 @@ declare module 'vscode' { * Create a new directory (Note, that new files are created via `write`-calls). * * @param uri The uri of the new folder. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when the parent of `uri` doesn't exist, e.g. no mkdirp-logic required. - * @throws {@link FileSystemError.FileExists `FileExists`} when `uri` already exists. - * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when the parent of `uri` doesn't exist, e.g. no mkdirp-logic required. + * @throws {@linkcode FileSystemError.FileExists FileExists} when `uri` already exists. + * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ createDirectory(uri: Uri): void | Thenable; @@ -7138,7 +7349,7 @@ declare module 'vscode' { * * @param uri The uri of the file. * @return An array of bytes or a thenable that resolves to such. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. */ readFile(uri: Uri): Uint8Array | Thenable; @@ -7148,10 +7359,10 @@ declare module 'vscode' { * @param uri The uri of the file. * @param content The new content of the file. * @param options Defines if missing files should or must be created. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist and `create` is not set. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when the parent of `uri` doesn't exist and `create` is set, e.g. no mkdirp-logic required. - * @throws {@link FileSystemError.FileExists `FileExists`} when `uri` already exists, `create` is set but `overwrite` is not set. - * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist and `create` is not set. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when the parent of `uri` doesn't exist and `create` is set, e.g. no mkdirp-logic required. + * @throws {@linkcode FileSystemError.FileExists FileExists} when `uri` already exists, `create` is set but `overwrite` is not set. + * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ writeFile(uri: Uri, content: Uint8Array, options: { create: boolean, overwrite: boolean }): void | Thenable; @@ -7160,8 +7371,8 @@ declare module 'vscode' { * * @param uri The resource that is to be deleted. * @param options Defines if deletion of folders is recursive. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. - * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist. + * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ delete(uri: Uri, options: { recursive: boolean }): void | Thenable; @@ -7171,10 +7382,10 @@ declare module 'vscode' { * @param oldUri The existing file. * @param newUri The new location. * @param options Defines if existing files should be overwritten. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `oldUri` doesn't exist. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required. - * @throws {@link FileSystemError.FileExists `FileExists`} when `newUri` exists and when the `overwrite` option is not `true`. - * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `oldUri` doesn't exist. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required. + * @throws {@linkcode FileSystemError.FileExists FileExists} when `newUri` exists and when the `overwrite` option is not `true`. + * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ rename(oldUri: Uri, newUri: Uri, options: { overwrite: boolean }): void | Thenable; @@ -7185,10 +7396,10 @@ declare module 'vscode' { * @param source The existing file. * @param destination The destination location. * @param options Defines if existing files should be overwritten. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `source` doesn't exist. - * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when parent of `destination` doesn't exist, e.g. no mkdirp-logic required. - * @throws {@link FileSystemError.FileExists `FileExists`} when `destination` exists and when the `overwrite` option is not `true`. - * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `source` doesn't exist. + * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when parent of `destination` doesn't exist, e.g. no mkdirp-logic required. + * @throws {@linkcode FileSystemError.FileExists FileExists} when `destination` exists and when the `overwrite` option is not `true`. + * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient. */ copy?(source: Uri, destination: Uri, options: { overwrite: boolean }): void | Thenable; } @@ -7199,7 +7410,7 @@ declare module 'vscode' { * with files from the local disk as well as files from remote places, like the * remote extension host or ftp-servers. * - * *Note* that an instance of this interface is available as {@link workspace.fs `workspace.fs`}. + * *Note* that an instance of this interface is available as {@linkcode workspace.fs}. */ export interface FileSystem { @@ -7313,6 +7524,14 @@ declare module 'vscode' { */ readonly enableScripts?: boolean; + /** + * Controls whether forms are enabled in the webview content or not. + * + * Defaults to true if {@link enableScripts scripts are enabled}. Otherwise defaults to false. + * Explicitly setting this property to either true or false overrides the default. + */ + readonly enableForms?: boolean; + /** * Controls whether command uris are enabled in webview content or not. * @@ -7360,7 +7579,7 @@ declare module 'vscode' { * This should be a complete, valid html document. Changing this property causes the webview to be reloaded. * * Webviews are sandboxed from normal extension process, so all communication with the webview must use - * message passing. To send a message from the extension to the webview, use {@link Webview.postMessage `postMessage`}. + * message passing. To send a message from the extension to the webview, use {@linkcode Webview.postMessage postMessage}. * To send message from the webview back to an extension, use the `acquireVsCodeApi` function inside the webview * to get a handle to the editor's api and then call `.postMessage()`: * @@ -7371,8 +7590,8 @@ declare module 'vscode' { * * ``` * - * To load a resources from the workspace inside a webview, use the `{@link Webview.asWebviewUri asWebviewUri}` method - * and ensure the resource's directory is listed in {@link WebviewOptions.localResourceRoots `WebviewOptions.localResourceRoots`}. + * To load a resources from the workspace inside a webview, use the {@linkcode Webview.asWebviewUri asWebviewUri} method + * and ensure the resource's directory is listed in {@linkcode WebviewOptions.localResourceRoots}. * * Keep in mind that even though webviews are sandboxed, they still allow running scripts and loading arbitrary content, * so extensions must follow all standard web security best practices when working with webviews. This includes @@ -7485,7 +7704,7 @@ declare module 'vscode' { iconPath?: Uri | { light: Uri; dark: Uri }; /** - * {@link Webview `Webview`} belonging to the panel. + * {@linkcode Webview} belonging to the panel. */ readonly webview: Webview; @@ -7605,8 +7824,8 @@ declare module 'vscode' { } /** - * A webview based view. - */ + * A webview based view. + */ export interface WebviewView { /** * Identifies the type of the webview view, such as `'hexEditor.dataView'`. @@ -7730,7 +7949,7 @@ declare module 'vscode' { /** * Provider for text based custom editors. * - * Text based custom editors use a {@link TextDocument `TextDocument`} as their data model. This considerably simplifies + * Text based custom editors use a {@linkcode TextDocument} as their data model. This considerably simplifies * implementing a custom editor as it allows the editor to handle many common operations such as * undo and backup. The provider is responsible for synchronizing text changes between the webview and the `TextDocument`. */ @@ -7749,7 +7968,7 @@ declare module 'vscode' { * * During resolve, the provider must fill in the initial html for the content webview panel and hook up all * the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to - * use later for example in a command. See {@link WebviewPanel `WebviewPanel`} for additional details. + * use later for example in a command. See {@linkcode WebviewPanel} for additional details. * * @param token A cancellation token that indicates the result is no longer needed. * @@ -7759,7 +7978,7 @@ declare module 'vscode' { } /** - * Represents a custom document used by a {@link CustomEditorProvider `CustomEditorProvider`}. + * Represents a custom document used by a {@linkcode CustomEditorProvider}. * * Custom documents are only used within a given `CustomEditorProvider`. The lifecycle of a `CustomDocument` is * managed by the editor. When no more references remain to a `CustomDocument`, it is disposed of. @@ -7780,9 +7999,9 @@ declare module 'vscode' { } /** - * Event triggered by extensions to signal to the editor that an edit has occurred on an {@link CustomDocument `CustomDocument`}. + * Event triggered by extensions to signal to the editor that an edit has occurred on an {@linkcode CustomDocument}. * - * @see {@link CustomEditorProvider.onDidChangeCustomDocument `CustomEditorProvider.onDidChangeCustomDocument`}. + * @see {@linkcode CustomEditorProvider.onDidChangeCustomDocument}. */ interface CustomDocumentEditEvent { @@ -7818,10 +8037,10 @@ declare module 'vscode' { } /** - * Event triggered by extensions to signal to the editor that the content of a {@link CustomDocument `CustomDocument`} + * Event triggered by extensions to signal to the editor that the content of a {@linkcode CustomDocument} * has changed. * - * @see {@link CustomEditorProvider.onDidChangeCustomDocument `CustomEditorProvider.onDidChangeCustomDocument`}. + * @see {@linkcode CustomEditorProvider.onDidChangeCustomDocument}. */ interface CustomDocumentContentChangeEvent { /** @@ -7831,7 +8050,7 @@ declare module 'vscode' { } /** - * A backup for an {@link CustomDocument `CustomDocument`}. + * A backup for an {@linkcode CustomDocument}. */ interface CustomDocumentBackup { /** @@ -7851,7 +8070,7 @@ declare module 'vscode' { } /** - * Additional information used to implement {@link CustomEditableDocument.backup `CustomEditableDocument.backup`}. + * Additional information used to implement {@linkcode CustomEditableDocument.backup}. */ interface CustomDocumentBackupContext { /** @@ -7889,10 +8108,10 @@ declare module 'vscode' { /** * Provider for readonly custom editors that use a custom document model. * - * Custom editors use {@link CustomDocument `CustomDocument`} as their document model instead of a {@link TextDocument `TextDocument`}. + * Custom editors use {@linkcode CustomDocument} as their document model instead of a {@linkcode TextDocument}. * * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple - * text based documents, use {@link CustomTextEditorProvider `CustomTextEditorProvider`} instead. + * text based documents, use {@linkcode CustomTextEditorProvider} instead. * * @param T Type of the custom document returned by this provider. */ @@ -7927,7 +8146,7 @@ declare module 'vscode' { * * During resolve, the provider must fill in the initial html for the content webview panel and hook up all * the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to - * use later for example in a command. See {@link WebviewPanel `WebviewPanel`} for additional details. + * use later for example in a command. See {@linkcode WebviewPanel} for additional details. * * @param token A cancellation token that indicates the result is no longer needed. * @@ -7939,11 +8158,11 @@ declare module 'vscode' { /** * Provider for editable custom editors that use a custom document model. * - * Custom editors use {@link CustomDocument `CustomDocument`} as their document model instead of a {@link TextDocument `TextDocument`}. + * Custom editors use {@linkcode CustomDocument} as their document model instead of a {@linkcode TextDocument}. * This gives extensions full control over actions such as edit, save, and backup. * * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple - * text based documents, use {@link CustomTextEditorProvider `CustomTextEditorProvider`} instead. + * text based documents, use {@linkcode CustomTextEditorProvider} instead. * * @param T Type of the custom document returned by this provider. */ @@ -8096,6 +8315,11 @@ declare module 'vscode' { */ export const appRoot: string; + /** + * The environment in which the app is hosted in. i.e. 'desktop', 'codespaces', 'web'. + */ + export const appHost: string; + /** * The custom uri scheme the editor registers to in the operating system. */ @@ -8172,7 +8396,7 @@ declare module 'vscode' { * * a mail client (`mailto:`) * * VSCode itself (`vscode:` from `vscode.env.uriScheme`) * - * *Note* that {@link window.showTextDocument `showTextDocument`} is the right + * *Note* that {@linkcode window.showTextDocument showTextDocument} is the right * way to open a text document inside the editor, not this function. * * @param target The uri that should be opened. @@ -8181,8 +8405,7 @@ declare module 'vscode' { export function openExternal(target: Uri): Thenable; /** - * Resolves a uri to form that is accessible externally. Currently only supports `https:`, `http:` and - * `vscode.env.uriScheme` uris. + * Resolves a uri to a form that is accessible externally. * * #### `http:` or `https:` scheme * @@ -8202,7 +8425,7 @@ declare module 'vscode' { * Creates a uri that - if opened in a browser (e.g. via `openExternal`) - will result in a registered {@link UriHandler} * to trigger. * - * Extensions should not make any assumptions about the resulting uri and should not alter it in anyway. + * Extensions should not make any assumptions about the resulting uri and should not alter it in any way. * Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query * argument to the server to authenticate to. * @@ -8227,6 +8450,11 @@ declare module 'vscode' { * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by * `asExternalUri`. * + * #### Any other scheme + * + * Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return + * a URI which, when handled, will make the editor open the workspace. + * * @return A uri that can be used on the client machine. */ export function asExternalUri(target: Uri): Thenable; @@ -8306,7 +8534,7 @@ declare module 'vscode' { * * * *Note 1:* When executing an editor command not all types are allowed to * be passed as arguments. Allowed are the primitive types `string`, `boolean`, - * `number`, `undefined`, and `null`, as well as {@link Position `Position`}, {@link Range `Range`}, {@link Uri `Uri`} and {@link Location `Location`}. + * `number`, `undefined`, and `null`, as well as {@linkcode Position}, {@linkcode Range}, {@linkcode Uri} and {@linkcode Location}. * * *Note 2:* There are no restrictions when executing commands that have been contributed * by extensions. * @@ -8451,7 +8679,7 @@ declare module 'vscode' { * * @param document A text document to be shown. * @param column A view column in which the {@link TextEditor editor} should be shown. The default is the {@link ViewColumn.Active active}, other values - * are adjusted to be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is not adjusted. Use {@link ViewColumn.Beside `ViewColumn.Beside`} + * 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. * @param preserveFocus When `true` the editor will not take focus. * @return A promise that resolves to an {@link TextEditor editor}. @@ -8792,7 +9020,7 @@ declare module 'vscode' { /** * Show progress in the editor. Progress is shown while running the given callback * and while the promise it returned isn't resolved nor rejected. The location at which - * progress should show (and other details) is defined via the passed {@link ProgressOptions `ProgressOptions`}. + * progress should show (and other details) is defined via the passed {@linkcode ProgressOptions}. * * @param task A callback returning a promise. Progress state can be reported with * the provided {@link Progress}-object. @@ -8802,7 +9030,7 @@ declare module 'vscode' { * e.g. `10` accounts for `10%` of work done). * Note that currently only `ProgressLocation.Notification` is capable of showing discrete progress. * - * To monitor if the operation has been cancelled by the user, use the provided {@link CancellationToken `CancellationToken`}. + * To monitor if the operation has been cancelled by the user, use the provided {@linkcode CancellationToken}. * Note that currently only `ProgressLocation.Notification` is supporting to show a cancel button to cancel the * long running operation. * @@ -8954,8 +9182,8 @@ declare module 'vscode' { * Register a provider for custom editors for the `viewType` contributed by the `customEditors` extension point. * * When a custom editor is opened, an `onCustomEditor:viewType` activation event is fired. Your extension - * must register a {@link CustomTextEditorProvider `CustomTextEditorProvider`}, {@link CustomReadonlyEditorProvider `CustomReadonlyEditorProvider`}, - * {@link CustomEditorProvider `CustomEditorProvider`}for `viewType` as part of activation. + * must register a {@linkcode CustomTextEditorProvider}, {@linkcode CustomReadonlyEditorProvider}, + * {@linkcode CustomEditorProvider}for `viewType` as part of activation. * * @param viewType Unique identifier for the custom editor provider. This should match the `viewType` from the * `customEditors` contribution point. @@ -8994,6 +9222,12 @@ declare module 'vscode' { */ export function registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable; + /** + * Registers a provider for a contributed terminal profile. + * @param id The ID of the contributed terminal profile. + * @param provider The terminal profile provider. + */ + export function registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable; /** * Register a file decoration provider. * @@ -9156,7 +9390,7 @@ declare module 'vscode' { * Get {@link TreeItem} representation of the `element` * * @param element The element for which {@link TreeItem} representation is asked for. - * @return {@link TreeItem} representation of the element + * @return TreeItem representation of the element. */ getTreeItem(element: T): TreeItem | Thenable; @@ -9385,6 +9619,18 @@ declare module 'vscode' { * a setting text style. */ message?: string; + + /** + * The icon path or {@link ThemeIcon} for the terminal. + */ + iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; + + /** + * The icon {@link ThemeColor} for the terminal. + * The `terminal.ansi*` theme keys are + * recommended for the best contrast and consistency across themes. + */ + color?: ThemeColor; } /** @@ -9401,6 +9647,18 @@ declare module 'vscode' { * control a terminal. */ pty: Pseudoterminal; + + /** + * The icon path or {@link ThemeIcon} for the terminal. + */ + iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; + + /** + * The icon {@link ThemeColor} for the terminal. + * The standard `terminal.ansi*` theme keys are + * recommended for the best contrast and consistency across themes. + */ + color?: ThemeColor; } /** @@ -9489,6 +9747,24 @@ declare module 'vscode' { */ onDidClose?: Event; + /** + * 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; + /** * Implement to handle when the pty is open and ready to start firing events. * @@ -9780,6 +10056,7 @@ declare module 'vscode' { /** * If the UI should stay open even when loosing UI focus. Defaults to false. + * This setting is ignored on iPad and is always false. */ ignoreFocusOut: boolean; @@ -9852,7 +10129,8 @@ declare module 'vscode' { buttons: readonly QuickInputButton[]; /** - * An event signaling when a button was triggered. + * An event signaling when a button in the title bar was triggered. + * This event does not fire for buttons on a {@link QuickPickItem}. */ readonly onDidTriggerButton: Event; @@ -9884,7 +10162,7 @@ declare module 'vscode' { /** * An event signaling when the active items have changed. */ - readonly onDidChangeActive: Event; + readonly onDidChangeActive: Event; /** * Selected items. This can be read and updated by the extension. @@ -9894,7 +10172,7 @@ declare module 'vscode' { /** * An event signaling when the selected items have changed. */ - readonly onDidChangeSelection: Event; + readonly onDidChangeSelection: Event; } /** @@ -10009,6 +10287,14 @@ declare module 'vscode' { readonly text: string; } + export enum TextDocumentChangeReason { + /** The text change is caused by an undo operation. */ + Undo = 1, + + /** The text change is caused by an redo operation. */ + Redo = 2, + } + /** * An event describing a transactional {@link TextDocument document} change. */ @@ -10023,6 +10309,12 @@ declare module 'vscode' { * An array of content changes. */ readonly contentChanges: readonly TextDocumentContentChangeEvent[]; + + /** + * The reason why the document was changed. + * Is undefined if the reason is not known. + */ + readonly reason?: TextDocumentChangeReason; } /** @@ -10051,7 +10343,7 @@ declare module 'vscode' { * An event that is fired when a {@link TextDocument document} will be saved. * * To make modifications to the document before it is being saved, call the - * {@link TextDocumentWillSaveEvent.waitUntil `waitUntil`}-function with a thenable + * {@linkcode TextDocumentWillSaveEvent.waitUntil waitUntil}-function with a thenable * that resolves to an array of {@link TextEdit text edits}. */ export interface TextDocumentWillSaveEvent { @@ -10102,7 +10394,7 @@ declare module 'vscode' { * An event that is fired when files are going to be created. * * To make modifications to the workspace before the files are created, - * call the {@link FileWillCreateEvent.waitUntil `waitUntil`}-function with a + * call the {@linkcode FileWillCreateEvent.waitUntil waitUntil}-function with a * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ export interface FileWillCreateEvent { @@ -10331,24 +10623,22 @@ declare module 'vscode' { export const fs: FileSystem; /** - * The workspace folder that is open in the editor. `undefined` when no workspace - * has been opened. + * The uri of the first entry of {@linkcode workspace.workspaceFolders workspaceFolders} + * as `string`. `undefined` if there is no first entry. * * Refer to https://code.visualstudio.com/docs/editor/workspaces for more information * on workspaces. * - * @deprecated Use {@link workspace.workspaceFolders `workspaceFolders`} instead. + * @deprecated Use {@linkcode workspace.workspaceFolders workspaceFolders} instead. */ export const rootPath: string | undefined; /** - * List of workspace folders that are open in the editor. `undefined` when no workspace + * List of workspace folders (0-N) that are open in the editor. `undefined` when no workspace * has been opened. * * Refer to https://code.visualstudio.com/docs/editor/workspaces for more information * on workspaces. - * - * *Note* that the first entry corresponds to the value of `rootPath`. */ export const workspaceFolders: readonly WorkspaceFolder[] | undefined; @@ -10433,7 +10723,7 @@ declare module 'vscode' { * one that called this method) will be terminated and restarted so that the (deprecated) `rootPath` property is * updated to point to the first workspace folder. * - * Use the {@link onDidChangeWorkspaceFolders `onDidChangeWorkspaceFolders()`} event to get notified when the + * Use the {@linkcode onDidChangeWorkspaceFolders onDidChangeWorkspaceFolders()} event to get notified when the * workspace folders have been updated. * * **Example:** adding a new workspace folder at the end of workspace folders @@ -10455,7 +10745,7 @@ declare module 'vscode' { * to rename that folder. * * **Note:** it is not valid to call {@link updateWorkspaceFolders updateWorkspaceFolders()} multiple times - * without waiting for the {@link onDidChangeWorkspaceFolders `onDidChangeWorkspaceFolders()`} to fire. + * without waiting for the {@linkcode onDidChangeWorkspaceFolders onDidChangeWorkspaceFolders()} to fire. * * @param start the zero-based location in the list of currently opened {@link WorkspaceFolder workspace folders} * from which to start deleting workspace folders. @@ -10542,14 +10832,15 @@ declare module 'vscode' { * * The document is denoted by an {@link Uri}. Depending on the {@link Uri.scheme scheme} the * following rules apply: - * * `file`-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded. - * * `untitled`-scheme: A new file that should be saved on disk, e.g. `untitled:c:\frodo\new.js`. The language - * will be derived from the file name. + * * `file`-scheme: Open a file on disk (`openTextDocument(Uri.file(path))`). Will be rejected if the file + * does not exist or cannot be loaded. + * * `untitled`-scheme: Open a blank untitled file with associated path (`openTextDocument(Uri.file(path).with({ scheme: 'untitled' }))`). + * The language will be derived from the file name. * * For all other schemes contributed {@link TextDocumentContentProvider text document content providers} and * {@link FileSystemProvider file system providers} are consulted. * * *Note* that the lifecycle of the returned document is owned by the editor and not by the extension. That means an - * {@link workspace.onDidCloseTextDocument `onDidClose`}-event can occur at any time after opening it. + * {@linkcode workspace.onDidCloseTextDocument onDidClose}-event can occur at any time after opening it. * * @param uri Identifies the resource to open. * @return A promise that resolves to a {@link TextDocument document}. @@ -10605,7 +10896,7 @@ declare module 'vscode' { * of a text document {@link languages.setTextDocumentLanguage has been changed}. * * *Note 1:* There is no guarantee that this event fires when an editor tab is closed, use the - * {@link window.onDidChangeVisibleTextEditors `onDidChangeVisibleTextEditors`}-event to know when editors change. + * {@linkcode window.onDidChangeVisibleTextEditors onDidChangeVisibleTextEditors}-event to know when editors change. * * *Note 2:* A document can be open but not shown in an editor which means this event can fire * for a document that has not been shown in an editor. @@ -10646,10 +10937,10 @@ declare module 'vscode' { /** * Open a notebook. Will return early if this notebook is already {@link notebook.notebookDocuments loaded}. Otherwise - * the notebook is loaded and the {@link notebook.onDidOpenNotebookDocument `onDidOpenNotebookDocument`}-event fires. + * the notebook is loaded and the {@linkcode notebook.onDidOpenNotebookDocument onDidOpenNotebookDocument}-event fires. * * *Note* that the lifecycle of the returned notebook is owned by the editor and not by the extension. That means an - * {@link notebook.onDidCloseNotebookDocument `onDidCloseNotebookDocument`}-event can occur at any time after. + * {@linkcode notebook.onDidCloseNotebookDocument onDidCloseNotebookDocument}-event can occur at any time after. * * *Note* that opening a notebook does not show a notebook editor. This function only returns a notebook document which * can be showns in a notebook editor but it can also be used for other things. @@ -10702,9 +10993,9 @@ declare module 'vscode' { * An event that is emitted when files are being created. * * *Note 1:* This event is triggered by user gestures, like creating a file from the - * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api. This event is *not* fired when + * explorer, or from the {@linkcode workspace.applyEdit}-api. This event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * {@link FileSystem `workspace.fs`}-api. + * {@linkcode FileSystem workspace.fs}-api. * * *Note 2:* When this event is fired, edits to files that are are being created cannot be applied. */ @@ -10714,9 +11005,9 @@ declare module 'vscode' { * An event that is emitted when files have been created. * * *Note:* This event is triggered by user gestures, like creating a file from the - * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when + * explorer, or from the {@linkcode workspace.applyEdit}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * {@link FileSystem `workspace.fs`}-api. + * {@linkcode FileSystem workspace.fs}-api. */ export const onDidCreateFiles: Event; @@ -10724,9 +11015,9 @@ declare module 'vscode' { * An event that is emitted when files are being deleted. * * *Note 1:* This event is triggered by user gestures, like deleting a file from the - * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when + * explorer, or from the {@linkcode workspace.applyEdit}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * {@link FileSystem `workspace.fs`}-api. + * {@linkcode FileSystem workspace.fs}-api. * * *Note 2:* When deleting a folder with children only one event is fired. */ @@ -10736,9 +11027,9 @@ declare module 'vscode' { * An event that is emitted when files have been deleted. * * *Note 1:* This event is triggered by user gestures, like deleting a file from the - * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when + * explorer, or from the {@linkcode workspace.applyEdit}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * {@link FileSystem `workspace.fs`}-api. + * {@linkcode FileSystem workspace.fs}-api. * * *Note 2:* When deleting a folder with children only one event is fired. */ @@ -10748,9 +11039,9 @@ declare module 'vscode' { * An event that is emitted when files are being renamed. * * *Note 1:* This event is triggered by user gestures, like renaming a file from the - * explorer, and from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when + * explorer, and from the {@linkcode workspace.applyEdit}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * {@link FileSystem `workspace.fs`}-api. + * {@linkcode FileSystem workspace.fs}-api. * * *Note 2:* When renaming a folder with children only one event is fired. */ @@ -10760,9 +11051,9 @@ declare module 'vscode' { * An event that is emitted when files have been renamed. * * *Note 1:* This event is triggered by user gestures, like renaming a file from the - * explorer, and from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when + * explorer, and from the {@linkcode workspace.applyEdit}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * {@link FileSystem `workspace.fs`}-api. + * {@linkcode FileSystem workspace.fs}-api. * * *Note 2:* When renaming a folder with children only one event is fired. */ @@ -10781,7 +11072,7 @@ declare module 'vscode' { * @param scope A scope for which the configuration is asked for. * @return The full configuration or a subset. */ - export function getConfiguration(section?: string | undefined, scope?: ConfigurationScope | null): WorkspaceConfiguration; + export function getConfiguration(section?: string, scope?: ConfigurationScope | null): WorkspaceConfiguration; /** * An event that is emitted when the {@link WorkspaceConfiguration configuration} changed. @@ -10887,8 +11178,8 @@ declare module 'vscode' { * Set (and change) the {@link TextDocument.languageId language} that is associated * with the given document. * - * *Note* that calling this function will trigger the {@link workspace.onDidCloseTextDocument `onDidCloseTextDocument`} event - * followed by the {@link workspace.onDidOpenTextDocument `onDidOpenTextDocument`} event. + * *Note* that calling this function will trigger the {@linkcode workspace.onDidCloseTextDocument onDidCloseTextDocument} event + * followed by the {@linkcode workspace.onDidOpenTextDocument onDidOpenTextDocument} event. * * @param document The document which language is to be changed * @param languageId The new language identifier. @@ -10901,9 +11192,9 @@ declare module 'vscode' { * greater than zero mean the selector matches the document. * * A match is computed according to these rules: - * 1. When {@link DocumentSelector `DocumentSelector`} is an array, compute the match for each contained `DocumentFilter` or language identifier and take the maximum value. - * 2. A string will be desugared to become the `language`-part of a {@link DocumentFilter `DocumentFilter`}, so `"fooLang"` is like `{ language: "fooLang" }`. - * 3. A {@link DocumentFilter `DocumentFilter`} will be matched against the document by comparing its parts with the document. The following rules apply: + * 1. When {@linkcode DocumentSelector} is an array, compute the match for each contained `DocumentFilter` or language identifier and take the maximum value. + * 2. A string will be desugared to become the `language`-part of a {@linkcode DocumentFilter}, so `"fooLang"` is like `{ language: "fooLang" }`. + * 3. A {@linkcode DocumentFilter} will be matched against the document by comparing its parts with the document. The following rules apply: * 1. When the `DocumentFilter` is empty (`{}`) the result is `0` * 2. When `scheme`, `language`, or `pattern` are defined but one doesn’t match, the result is `0` * 3. Matching against `*` gives a score of `5`, matching via equality or via a glob-pattern gives a score of `10` @@ -11327,6 +11618,15 @@ declare module 'vscode' { */ export function registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable; + /** + * 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 {@link Disposable Disposable} that unregisters this provider when being disposed. + */ + export function registerTypeHierarchyProvider(selector: DocumentSelector, provider: TypeHierarchyProvider): Disposable; + /** * Register a linked editing range provider. * @@ -11401,7 +11701,7 @@ declare module 'vscode' { /** * The metadata of this cell. Can be anything but must be JSON-stringifyable. */ - readonly metadata: { [key: string]: any } + readonly metadata: { [key: string]: any }; /** * The outputs of this cell. @@ -11409,11 +11709,44 @@ declare module 'vscode' { readonly outputs: readonly NotebookCellOutput[]; /** - * The most recent {@link NotebookCellExecutionSummary excution summary} for this cell. + * The most recent {@link NotebookCellExecutionSummary execution summary} for this cell. */ readonly executionSummary?: NotebookCellExecutionSummary; } + /** + * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}. + * Additional properties of the NotebookEditor are available in the proposed + * API, which will be finalized later. + */ + export interface NotebookEditor { + + } + + /** + * Renderer messaging is used to communicate with a single renderer. It's returned from {@link notebooks.createRendererMessaging}. + */ + export interface NotebookRendererMessaging { + /** + * An event that fires when a message is received from a renderer. + */ + readonly onDidReceiveMessage: Event<{ + readonly editor: NotebookEditor; + readonly message: any; + }>; + + /** + * Send a message to one or all renderer. + * + * @param message Message to send + * @param editor Editor to target with the message. If not provided, the + * message is sent to all renderers. + * @returns a boolean indicating whether the message was successfully + * delivered to any renderer. + */ + postMessage(message: any, editor?: NotebookEditor): Thenable; + } + /** * Represents a notebook which itself is a sequence of {@link NotebookCell code or markup cells}. Notebook documents are * created from {@link NotebookData notebook data}. @@ -11477,7 +11810,7 @@ declare module 'vscode' { /** * Get the cells of this notebook. A subset can be retrieved by providing - * a range. The range will be adjuset to the notebook. + * a range. The range will be adjusted to the notebook. * * @param range A notebook range. * @returns The cells contained by the range or all cells. @@ -11504,7 +11837,7 @@ declare module 'vscode' { readonly executionOrder?: number; /** - * If the exclusive finished successfully. + * If the execution finished successfully. */ readonly success?: boolean; @@ -11515,7 +11848,7 @@ declare module 'vscode' { } /** - * A notebook range represents an ordered pair of two cell indicies. + * A notebook range represents an ordered pair of two cell indices. * It is guaranteed that start is less than or equal to end. */ export class NotebookRange { @@ -11612,7 +11945,7 @@ declare module 'vscode' { static error(value: Error): NotebookCellOutputItem; /** - * The mime type which determines how the {@link NotebookCellOutputItem.data `data`}-property + * The mime type which determines how the {@linkcode NotebookCellOutputItem.data data}-property * is interpreted. * * Notebooks have built-in support for certain mime-types, extensions can add support for new @@ -11626,7 +11959,7 @@ declare module 'vscode' { data: Uint8Array; /** - * Create a new notbook cell output item. + * Create a new notebook cell output item. * * @param data The value of the output item. * @param mime The mime type of the output item. @@ -11671,7 +12004,7 @@ declare module 'vscode' { } /** - * NotebookCellData is the raw representation of notebook cells. Its is part of {@link NotebookData `NotebookData`}. + * NotebookCellData is the raw representation of notebook cells. Its is part of {@linkcode NotebookData}. */ export class NotebookCellData { @@ -11687,7 +12020,7 @@ declare module 'vscode' { /** * The language identifier of the source value of this cell data. Any value from - * {@link languages.getLanguages `getLanguages`} is possible. + * {@linkcode languages.getLanguages getLanguages} is possible. */ languageId: string; @@ -11718,10 +12051,10 @@ declare module 'vscode' { } /** - * NotebookData is the raw representation of notebooks. + * Raw representation of a notebook. * - * Extensions are responsible to create {@link NotebookData `NotebookData`} so that the editor - * can create a {@link NotebookDocument `NotebookDocument`}. + * Extensions are responsible for creating {@linkcode NotebookData} so that the editor + * can create a {@linkcode NotebookDocument}. * * @see {@link NotebookSerializer} */ @@ -11819,12 +12152,12 @@ declare module 'vscode' { * A notebook controller represents an entity that can execute notebook cells. This is often referred to as a kernel. * * There can be multiple controllers and the editor will let users choose which controller to use for a certain notebook. The - * {@link NotebookController.notebookType `notebookType`}-property defines for what kind of notebooks a controller is for and - * the {@link NotebookController.updateNotebookAffinity `updateNotebookAffinity`}-function allows controllers to set a preference + * {@linkcode NotebookController.notebookType notebookType}-property defines for what kind of notebooks a controller is for and + * the {@linkcode NotebookController.updateNotebookAffinity updateNotebookAffinity}-function allows controllers to set a preference * for specific notebook documents. When a controller has been selected its * {@link NotebookController.onDidChangeSelectedNotebooks onDidChangeSelectedNotebooks}-event fires. * - * When a cell is being run the editor will invoke the {@link NotebookController.executeHandler `executeHandler`} and a controller + * When a cell is being run the editor will invoke the {@linkcode NotebookController.executeHandler executeHandler} and a controller * is expected to create and finalize a {@link NotebookCellExecution notebook cell execution}. However, controllers are also free * to create executions by themselves. */ @@ -11845,7 +12178,7 @@ declare module 'vscode' { /** * An array of language identifiers that are supported by this - * controller. Any language identifier from {@link languages.getLanguages `getLanguages`} + * controller. Any language identifier from {@linkcode languages.getLanguages getLanguages} * is possible. When falsy all languages are supported. * * Samples: @@ -11947,9 +12280,9 @@ declare module 'vscode' { * A NotebookCellExecution is how {@link NotebookController notebook controller} modify a notebook cell as * it is executing. * - * When a cell execution object is created, the cell enters the {@link NotebookCellExecutionState.Pending `Pending`} state. - * When {@link NotebookCellExecution.start `start(...)`} is called on the execution task, it enters the {@link NotebookCellExecutionState.Executing `Executing`} state. When - * {@link NotebookCellExecution.end `end(...)`} is called, it enters the {@link NotebookCellExecutionState.Idle `Idle`} state. + * When a cell execution object is created, the cell enters the {@linkcode NotebookCellExecutionState.Pending Pending} state. + * When {@linkcode NotebookCellExecution.start start(...)} is called on the execution task, it enters the {@linkcode NotebookCellExecutionState.Executing Executing} state. When + * {@linkcode NotebookCellExecution.end end(...)} is called, it enters the {@linkcode NotebookCellExecutionState.Idle Idle} state. */ export interface NotebookCellExecution { @@ -12069,11 +12402,11 @@ declare module 'vscode' { alignment: NotebookCellStatusBarAlignment; /** - * An optional {@link Command `Command`} or identifier of a command to run on click. + * An optional {@linkcode Command} or identifier of a command to run on click. * * The command must be {@link commands.getCommands known}. * - * Note that if this is a {@link Command `Command`} object, only the {@link Command.command `command`} and {@link Command.arguments `arguments`} + * Note that if this is a {@linkcode Command} object, only the {@linkcode Command.command command} and {@linkcode Command.arguments arguments} * are used by the editor. */ command?: string | Command; @@ -12122,7 +12455,7 @@ declare module 'vscode' { /** * Namespace for notebooks. * - * The notebooks functionality is composed of three loosly coupled components: + * The notebooks functionality is composed of three loosely coupled components: * * 1. {@link NotebookSerializer} enable the editor to open, show, and save notebooks * 2. {@link NotebookController} own the execution of notebooks, e.g they create output from code cells. @@ -12148,6 +12481,18 @@ declare module 'vscode' { * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable; + + /** + * Creates a new messaging instance used to communicate with a specific renderer. + * + * * *Note 1:* Extensions can only create renderer that they have defined in their `package.json`-file + * * *Note 2:* A renderer only has access to messaging if `requiresMessaging` is set to `always` or `optional` in + * its `notebookRenderer` contribution. + * + * @param rendererId The renderer ID to communicate with + * @returns A new notebook renderer messaging object. + */ + export function createRendererMessaging(rendererId: string): NotebookRendererMessaging; } /** @@ -12193,7 +12538,7 @@ declare module 'vscode' { * The icon path for a specific * {@link SourceControlResourceState source control resource state}. */ - readonly iconPath?: string | Uri; + readonly iconPath?: string | Uri | ThemeIcon; } /** @@ -12878,6 +13223,13 @@ declare module 'vscode' { */ parentSession?: DebugSession; + /** + * Controls whether lifecycle requests like 'restart' are sent to the newly created session or its parent session. + * By default (if the property is false or missing), lifecycle requests are sent to the new session. + * This property is ignored if the session has no parent session. + */ + lifecycleManagedByParent?: boolean; + /** * Controls whether this session should have a separate debug console or share it * with the parent session. Has no effect for sessions which do not have a parent session. @@ -13512,17 +13864,17 @@ declare module 'vscode' { */ export interface AuthenticationProviderAuthenticationSessionsChangeEvent { /** - * The {@link AuthenticationSession}s of the {@link AuthentiationProvider AuthenticationProvider} that have been added. + * The {@link AuthenticationSession}s of the {@link AuthenticationProvider} that have been added. */ readonly added?: readonly AuthenticationSession[]; /** - * The {@link AuthenticationSession}s of the {@link AuthentiationProvider AuthenticationProvider} that have been removed. + * The {@link AuthenticationSession}s of the {@link AuthenticationProvider} that have been removed. */ readonly removed?: readonly AuthenticationSession[]; /** - * The {@link AuthenticationSession}s of the {@link AuthentiationProvider AuthenticationProvider} that have been changed. + * The {@link AuthenticationSession}s of the {@link AuthenticationProvider} that have been changed. * A session changes when its data excluding the id are updated. An example of this is a session refresh that results in a new * access token being set for the session. */ @@ -13588,7 +13940,7 @@ declare module 'vscode' { * 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 GetSessionOptions} to use + * @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 & { createIfNone: true }): Thenable; @@ -13603,7 +13955,7 @@ declare module 'vscode' { * 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 GetSessionOptions} to use + * @param options The {@link AuthenticationGetSessionOptions} to use * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions */ export function getSession(providerId: string, scopes: readonly string[], options?: AuthenticationGetSessionOptions): Thenable; @@ -13628,6 +13980,523 @@ declare module 'vscode' { */ export function registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable; } + + /** + * Namespace for testing functionality. Tests are published by registering + * {@link TestController} instances, then adding {@link TestItem TestItems}. + * Controllers may also describe how to run tests by creating one or more + * {@link TestRunProfile} instances. + */ + export namespace tests { + /** + * Creates a new test controller. + * + * @param id Identifier for the controller, must be globally unique. + * @param label A human-readable label for the controller. + * @returns An instance of the {@link TestController}. + */ + export function createTestController(id: string, label: string): TestController; + } + + /** + * The kind of executions that {@link TestRunProfile TestRunProfiles} control. + */ + export enum TestRunProfileKind { + Run = 1, + Debug = 2, + Coverage = 3, + } + + /** + * 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); + } + + /** + * A TestRunProfile describes one way to execute tests in a {@link TestController}. + */ + export interface TestRunProfile { + /** + * Label shown to the user in the UI. + * + * Note that the label has some significance if the user requests that + * tests be re-run in a certain way. For example, if tests were run + * normally and the user requests to re-run them in debug mode, the editor + * will attempt use a configuration with the same label of the `Debug` + * kind. If there is no such configuration, the default will be used. + */ + label: string; + + /** + * Configures what kind of execution this profile controls. If there + * are no profiles for a kind, it will not be available in the UI. + */ + readonly kind: TestRunProfileKind; + + /** + * Controls whether this profile is the default action that will + * be taken when its kind is actioned. For example, if the user clicks + * the generic "run all" button, then the default profile for + * {@link TestRunProfileKind.Run} will be executed, although the + * user can configure this. + */ + isDefault: boolean; + + /** + * 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; + + /** + * If this method is present, a configuration gear will be present in the + * UI, and this method will be invoked when it's clicked. When called, + * you can take other editor actions, such as showing a quick pick or + * opening a configuration file. + */ + configureHandler?: () => void; + + /** + * Handler called to start a test run. When invoked, the function should call + * {@link TestController.createTestRun} at least once, and all test runs + * associated with the request should be created before the function returns + * or the returned promise is resolved. + * + * @param request Request information for the test run. + * @param cancellationToken Token that signals the used asked to abort the + * test run. If cancellation is requested on this token, all {@link TestRun} + * instances associated with the request will be + * automatically cancelled as well. + */ + runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable | void; + + /** + * Deletes the run profile. + */ + dispose(): void; + } + + /** + * Entry point to discover and execute tests. It contains {@link TestController.items} which + * are used to populate the editor UI, and is associated with + * {@link TestController.createRunProfile run profiles} to allow + * for tests to be executed. + */ + export interface TestController { + /** + * The id of the controller passed in {@link vscode.tests.createTestController}. + * This must be globally unique. + */ + readonly id: string; + + /** + * Human-readable label for the test controller. + */ + label: string; + + /** + * A collection of "top-level" {@link TestItem} instances, which can in + * turn have their own {@link TestItem.children children} to form the + * "test tree." + * + * The extension controls when to add tests. For example, extensions should + * add tests for a file when {@link vscode.workspace.onDidOpenTextDocument} + * fires in order for decorations for tests within a file to be visible. + * + * However, the editor may sometimes explicitly request children using the + * {@link resolveHandler} See the documentation on that method for more details. + */ + readonly items: TestItemCollection; + + /** + * Creates a profile used for running tests. Extensions must create + * at least one profile in order for tests to be run. + * @param label A human-readable label for this profile. + * @param kind Configures what kind of execution this profile manages. + * @param runHandler Function called to start a test run. + * @param isDefault Whether this is the default action for its kind. + * @param tag Profile test tag. + * @returns An instance of a {@link TestRunProfile}, which is automatically + * associated with this controller. + */ + createRunProfile(label: string, kind: TestRunProfileKind, runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable | void, isDefault?: boolean, tag?: TestTag): TestRunProfile; + + /** + * A function provided by the extension that the editor may call to request + * children of a test item, if the {@link TestItem.canResolveChildren} is + * `true`. When called, the item should discover children and call + * {@link vscode.tests.createTestItem} as children are discovered. + * + * Generally the extension manages the lifecycle of test items, but under + * certain conditions the editor may request the children of a specific + * item to be loaded. For example, if the user requests to re-run tests + * after reloading the editor, the editor may need to call this method + * to resolve the previously-run tests. + * + * The item in the explorer will automatically be marked as "busy" until + * the function returns or the returned thenable resolves. + * + * @param item An unresolved test item for which children are being + * requested, or `undefined` to resolve the controller's initial {@link items}. + */ + resolveHandler?: (item: TestItem | undefined) => Thenable | void; + + /** + * Creates a {@link TestRun}. This should be called by the + * {@link TestRunProfile} when a request is made to execute tests, and may + * also be called if a test run is detected externally. Once created, tests + * that are included in the request will be moved into the queued state. + * + * All runs created using the same `request` instance will be grouped + * together. This is useful if, for example, a single suite of tests is + * run on multiple platforms. + * + * @param request Test run request. Only tests inside the `include` may be + * modified, and tests in its `exclude` are ignored. + * @param name The human-readable name of the run. This can be used to + * disambiguate multiple sets of results in a test run. It is useful if + * tests are run across multiple platforms, for example. + * @param persist Whether the results created by the run should be + * persisted in the editor. This may be false if the results are coming from + * a file already saved externally, such as a coverage information file. + * @returns An instance of the {@link TestRun}. It will be considered "running" + * from the moment this method is invoked until {@link TestRun.end} is called. + */ + createTestRun(request: TestRunRequest, name?: string, persist?: boolean): TestRun; + + /** + * Creates a new managed {@link TestItem} instance. It can be added into + * the {@link TestItem.children} of an existing item, or into the + * {@link TestController.items}. + * + * @param id Identifier for the TestItem. The test item's ID must be unique + * in the {@link TestItemCollection} it's added to. + * @param label Human-readable label of the test item. + * @param uri URI this TestItem is associated with. May be a file or directory. + */ + createTestItem(id: string, label: string, uri?: Uri): TestItem; + + /** + * Unregisters the test controller, disposing of its associated tests + * and unpersisted results. + */ + dispose(): void; + } + + /** + * A TestRunRequest is a precursor to a {@link TestRun}, which in turn is + * created by passing a request to {@link tests.runTests}. The TestRunRequest + * contains information about which tests should be run, which should not be + * run, and how they are run (via the {@link profile}). + * + * In general, TestRunRequests are created by the editor and pass to + * {@link TestRunProfile.runHandler}, however you can also create test + * requests and runs outside of the `runHandler`. + */ + export class TestRunRequest { + /** + * A filter for specific tests to run. If given, the extension should run + * all of the included tests and all their children, excluding any tests + * that appear in {@link TestRunRequest.exclude}. If this property is + * undefined, then the extension should simply run all tests. + * + * The process of running tests should resolve the children of any test + * items who have not yet been resolved. + */ + readonly include?: TestItem[]; + + /** + * An array of tests the user has marked as excluded from the test included + * in this run; exclusions should apply after inclusions. + * + * May be omitted if no exclusions were requested. Test controllers should + * not run excluded tests or any children of excluded tests. + */ + readonly exclude?: TestItem[]; + + /** + * The profile used for this request. This will always be defined + * for requests issued from the editor UI, though extensions may + * programmatically create requests not associated with any profile. + */ + readonly profile?: TestRunProfile; + + /** + * @param tests Array of specific tests to run, or undefined to run all tests + * @param exclude An array of tests to exclude from the run. + * @param profile The run profile used for this request. + */ + constructor(include?: readonly TestItem[], exclude?: readonly TestItem[], profile?: TestRunProfile); + } + + /** + * Options given to {@link TestController.runTests} + */ + export interface TestRun { + /** + * The human-readable name of the run. This can be used to + * disambiguate multiple sets of results in a test run. It is useful if + * tests are run across multiple platforms, for example. + */ + readonly name?: string; + + /** + * A cancellation token which will be triggered when the test run is + * canceled from the UI. + */ + readonly token: CancellationToken; + + /** + * Whether the test run will be persisted across reloads by the editor. + */ + readonly isPersisted: boolean; + + /** + * Indicates a test is queued for later execution. + * @param test Test item to update. + */ + enqueued(test: TestItem): void; + + /** + * Indicates a test has started running. + * @param test Test item to update. + */ + started(test: TestItem): void; + + /** + * Indicates a test has been skipped. + * @param test Test item to update. + */ + skipped(test: TestItem): void; + + /** + * Indicates a test has failed. You should pass one or more + * {@link TestMessage TestMessages} to describe the failure. + * @param test Test item to update. + * @param messages Messages associated with the test failure. + * @param duration How long the test took to execute, in milliseconds. + */ + failed(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void; + + /** + * Indicates a test has errored. You should pass one or more + * {@link TestMessage TestMessages} to describe the failure. This differs + * from the "failed" state in that it indicates a test that couldn't be + * executed at all, from a compilation error for example. + * @param test Test item to update. + * @param messages Messages associated with the test failure. + * @param duration How long the test took to execute, in milliseconds. + */ + errored(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void; + + /** + * Indicates a test has passed. + * @param test Test item to update. + * @param duration How long the test took to execute, in milliseconds. + */ + passed(test: TestItem, duration?: number): void; + + /** + * 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; + + /** + * Signals that the end of the test run. Any tests included in the run whose + * states have not been updated will have their state reset. + */ + end(): void; + } + + /** + * Collection of test items, found in {@link TestItem.children} and + * {@link TestController.items}. + */ + export interface TestItemCollection { + /** + * Gets the number of items in the collection. + */ + readonly size: number; + + /** + * Replaces the items stored by the collection. + * @param items Items to store. + */ + replace(items: readonly TestItem[]): void; + + /** + * Iterate over each entry in this collection. + * + * @param callback Function to execute for each entry. + * @param thisArg The `this` context used when invoking the handler function. + */ + forEach(callback: (item: TestItem, collection: TestItemCollection) => unknown, thisArg?: unknown): void; + + /** + * Adds the test item to the children. If an item with the same ID already + * exists, it'll be replaced. + * @param items Item to add. + */ + add(item: TestItem): void; + + /** + * Removes a single test item from the collection. + * @param itemId Item ID to delete. + */ + delete(itemId: string): void; + + /** + * Efficiently gets a test item by ID, if it exists, in the children. + * @param itemId Item ID to get. + * @returns The found item or undefined if it does not exist. + */ + get(itemId: string): TestItem | undefined; + } + + /** + * An item shown in the "test explorer" view. + * + * A `TestItem` can represent either a test suite or a test itself, since + * they both have similar capabilities. + */ + export interface TestItem { + /** + * Identifier for the `TestItem`. This is used to correlate + * test results and tests in the document with those in the workspace + * (test explorer). This cannot change for the lifetime of the `TestItem`, + * and must be unique among its parent's direct children. + */ + readonly id: string; + + /** + * URI this `TestItem` is associated with. May be a file or directory. + */ + readonly uri?: Uri; + + /** + * The children of this test item. For a test suite, this may contain the + * individual test cases or nested suites. + */ + readonly children: TestItemCollection; + + /** + * The parent of this item. It's set automatically, and is undefined + * top-level items in the {@link TestController.items} and for items that + * aren't yet included in another item's {@link children}. + */ + readonly parent?: 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[]; + + /** + * Indicates whether this test item may have children discovered by resolving. + * + * If true, this item is shown as expandable in the Test Explorer view and + * expanding the item will cause {@link TestController.resolveHandler} + * to be invoked with the item. + * + * Default to `false`. + */ + canResolveChildren: boolean; + + /** + * Controls whether the item is shown as "busy" in the Test Explorer view. + * This is useful for showing status while discovering children. + * + * Defaults to `false`. + */ + busy: boolean; + + /** + * Display name describing the test case. + */ + label: string; + + /** + * Optional description that appears next to the label. + */ + description?: string; + + /** + * Location of the test item in its {@link uri}. + * + * This is only meaningful if the `uri` points to a file. + */ + range?: Range; + + /** + * Optional error encountered while loading the test. + * + * Note that this is not a test result and should only be used to represent errors in + * test discovery, such as syntax errors. + */ + error?: string | MarkdownString; + } + + /** + * Message associated with the test state. Can be linked to a specific + * source range -- useful for assertion failures, for example. + */ + export class TestMessage { + /** + * Human-readable message text to display. + */ + message: string | MarkdownString; + + /** + * Expected test output. If given with {@link actualOutput}, a diff view will be shown. + */ + expectedOutput?: string; + + /** + * Actual test output. If given with {@link expectedOutput}, a diff view will be shown. + */ + actualOutput?: string; + + /** + * Associated file location. + */ + location?: Location; + + /** + * Creates a new TestMessage that will present as a diff in the editor. + * @param message Message to display to the user. + * @param expected Expected output. + * @param actual Actual output. + */ + static diff(message: string | MarkdownString, expected: string, actual: string): TestMessage; + + /** + * Creates a new TestMessage instance. + * @param message The message to show to the user. + */ + constructor(message: string | MarkdownString); + } } /** diff --git a/vscode.proposed.d.ts b/vscode.proposed.d.ts index 7924435..89f26ec 100644 --- a/vscode.proposed.d.ts +++ b/vscode.proposed.d.ts @@ -16,48 +16,6 @@ declare module 'vscode' { - //#region auth provider: https://github.com/microsoft/vscode/issues/88309 - - /** - * An {@link Event} which fires when an {@link AuthenticationProvider} is added or removed. - */ - export interface AuthenticationProvidersChangeEvent { - /** - * The ids of the {@link AuthenticationProvider}s that have been added. - */ - readonly added: ReadonlyArray; - - /** - * The ids of the {@link AuthenticationProvider}s that have been removed. - */ - readonly removed: ReadonlyArray; - } - - export namespace authentication { - /** - * @deprecated - getSession should now trigger extension activation. - * Fires with the provider id that was registered or unregistered. - */ - export const onDidChangeAuthenticationProviders: Event; - - /** - * @deprecated - * An array of the information of authentication providers that are currently registered. - */ - export const providers: ReadonlyArray; - - /** - * @deprecated - * Logout of a specific session. - * @param providerId The id of the provider to use - * @param sessionId The session id to remove - * provider - */ - export function logout(providerId: string, sessionId: string): Thenable; - } - - //#endregion - // eslint-disable-next-line vscode-dts-region-comments //#region @alexdima - resolvers @@ -92,6 +50,7 @@ declare module 'vscode' { localAddressPort?: number; label?: string; public?: boolean; + protocol?: string; } export interface TunnelDescription { @@ -99,6 +58,8 @@ declare module 'vscode' { //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 { @@ -189,6 +150,38 @@ declare module 'vscode' { 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. @@ -226,6 +219,7 @@ declare module 'vscode' { tildify?: boolean; normalizeDriveLetter?: boolean; workspaceSuffix?: string; + workspaceTooltip?: string; authorityPrefix?: string; stripPathStartingSeparator?: boolean; } @@ -235,6 +229,21 @@ declare module 'vscode' { export function registerResourceLabelFormatter(formatter: ResourceLabelFormatter): Disposable; } + export namespace env { + + /** + * The authority part of the current opened `vscode-remote://` URI. + * Defined by extensions, e.g. `ssh-remote+${host}` for remotes using a secure shell. + * + * *Note* that the value is `undefined` when there is no remote extension host but that the + * value is defined in all extension hosts (local and remote) in case a remote extension host + * exists. Use {@link Extension.extensionKind} to know if + * a specific extension runs remote or not. + */ + export const remoteAuthority: string | undefined; + + } + //#endregion //#region editor insets: https://github.com/microsoft/vscode/issues/85682 @@ -428,7 +437,7 @@ declare module 'vscode' { export interface TextSearchComplete { /** * Whether the search hit the limit on the maximum number of search results. - * `maxResults` on {@link TextSearchOptions `TextSearchOptions`} specifies the max number of 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. @@ -721,6 +730,29 @@ declare module 'vscode' { //#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 @@ -771,7 +803,7 @@ declare module 'vscode' { /** * The validation message to display. */ - readonly message: string; + readonly message: string | MarkdownString; /** * The validation type. @@ -787,7 +819,7 @@ declare module 'vscode' { /** * Shows a transient contextual message on the input. */ - showValidationMessage(message: string, type: SourceControlInputBoxValidationType): void; + showValidationMessage(message: string | MarkdownString, type: SourceControlInputBoxValidationType): void; /** * A validation function for the input box. It's possible to change @@ -874,65 +906,106 @@ declare module 'vscode' { //#endregion - //#region Terminal name change event https://github.com/microsoft/vscode/issues/114898 + //#region Terminal state event https://github.com/microsoft/vscode/issues/127717 - export interface Pseudoterminal { + /** + * Represents the state of a {@link Terminal}. + */ + export interface TerminalState { /** - * An event that when fired allows changing the name of the terminal. + * 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: * - * **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 }); - * ``` + * - 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 */ - onDidChangeName?: Event; + // todo@API Maybe, isInteractedWith to align with other isXYZ + readonly interactedWith: boolean; } - //#endregion - - //#region Terminal icon https://github.com/microsoft/vscode/issues/120538 - - export interface TerminalOptions { + export interface Terminal { /** - * The icon path or {@link ThemeIcon} for the terminal. + * The current state of the {@link Terminal}. */ - readonly iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; + readonly state: TerminalState; } - export interface ExtensionTerminalOptions { + export namespace window { /** - * A themeIcon, Uri, or light and dark Uris to use as the terminal tab icon + * An {@link Event} which fires when a {@link Terminal.state terminal's state} has changed. */ - readonly iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; + export const onDidChangeTerminalState: Event; } //#endregion - //#region Terminal profile provider https://github.com/microsoft/vscode/issues/120369 + //#region Terminal location https://github.com/microsoft/vscode/issues/45407 - export namespace window { + 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; /** - * Registers a provider for a contributed terminal profile. - * @param id The ID of the contributed terminal profile. - * @param provider The terminal profile provider. + * An optional flag that when `true` will stop the {@link Terminal} from taking focus. */ - export function registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable; + preserveFocus?: boolean; } - export interface TerminalProfileProvider { + export interface TerminalSplitLocationOptions { /** - * Provide terminal profile options for the requested terminal. - * @param token A cancellation token that indicates the result is no longer needed. + * 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 }); + * ``` */ - provideProfileOptions(token: CancellationToken): ProviderResult; + onDidChangeName?: Event; } //#endregion @@ -953,18 +1026,66 @@ declare module 'vscode' { //#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: T[], target: T): Thenable; + onDrop(source: TreeDataTransfer, target: T): Thenable; } //#endregion @@ -974,6 +1095,11 @@ declare module 'vscode' { * 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 @@ -1012,6 +1138,18 @@ declare module 'vscode' { //#endregion + //#region https://github.com/microsoft/vscode/issues/132068 + + export interface QuickPick extends QuickInput { + + /* + * 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 /** @@ -1416,73 +1554,8 @@ declare module 'vscode' { //#endregion - //#region https://github.com/microsoft/vscode/issues/39441 - - export interface CompletionItem { - /** - * Will be merged into CompletionItem#label - */ - label2?: CompletionItemLabel; - } - - export interface CompletionItemLabel { - /** - * The function or variable. Rendered leftmost. - */ - name: string; - - /** - * The parameters without the return type. Render after `name`. - */ - //todo@API rename to signature - parameters?: string; - - /** - * The fully qualified name, like package name or file path. Rendered after `signature`. - */ - //todo@API find better name - qualifier?: string; - - /** - * The return-type of a function or type of a property/variable. Rendered rightmost. - */ - type?: string; - } - - //#endregion - //#region @https://github.com/microsoft/vscode/issues/123601, notebook messaging - export interface NotebookRendererMessage { - /** - * Editor that sent the message. - */ - editor: NotebookEditor; - - /** - * Message sent from the webview. - */ - message: T; - } - - /** - * Renderer messaging is used to communicate with a single renderer. It's - * returned from {@link notebooks.createRendererMessaging}. - */ - export interface NotebookRendererMessaging { - /** - * Events that fires when a message is received from a renderer. - */ - onDidReceiveMessage: Event>; - - /** - * Sends a message to the renderer. - * @param editor Editor to target with the message - * @param message Message to send - */ - postMessage(editor: NotebookEditor, message: TSend): void; - } - /** * 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. @@ -1497,12 +1570,14 @@ declare module 'vscode' { provides: string[]; /** - * URI for the file to preload + * URI of the JavaScript module to preload. + * + * This module must export an `activate` function that takes a context object that contains the notebook API. */ uri: Uri; /** - * @param uri URI for the file to preload + * @param uri URI of the JavaScript module to preload * @param provides Value for the `provides` property */ constructor(uri: Uri, provides?: string | string[]); @@ -1538,18 +1613,6 @@ declare module 'vscode' { export namespace notebooks { export function createNotebookController(id: string, viewType: string, label: string, handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable, rendererScripts?: NotebookRendererScript[]): NotebookController; - - /** - * Creates a new messaging instance used to communicate with a specific - * renderer. The renderer only has access to messaging if `requiresMessaging` - * is set to `always` or `optional` in its `notebookRenderer ` contribution. - * - * @see https://github.com/microsoft/vscode/issues/123601 - * @param rendererId The renderer ID to communicate with - */ - // todo@API can ANY extension talk to renderer or is there a check that the calling extension - // declared the renderer in its package.json? - export function createRendererMessaging(rendererId: string): NotebookRendererMessaging; } //#endregion @@ -1844,86 +1907,36 @@ declare module 'vscode' { } //#endregion - //#region https://github.com/microsoft/vscode/issues/107467 - export namespace test { - /** - * Registers a controller that can discover and - * run tests in workspaces and documents. - */ - export function registerTestController(testController: TestController): Disposable; - + //#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 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 retrieves tests in the given workspace folder. - * @stability experimental - */ - export function createWorkspaceTestObserver(workspaceFolder: WorkspaceFolder): TestObserver; - - /** - * Returns an observer that retrieves tests in the given text document. - * @stability experimental - */ - export function createDocumentTestObserver(document: TextDocument): TestObserver; + export function runTests(run: TestRunRequest, token?: CancellationToken): Thenable; /** - * Creates a {@link TestRun}. This should be called by the - * {@link TestRunner} when a request is made to execute tests, and may also - * be called if a test run is detected externally. Once created, tests - * that are included in the results will be moved into the - * {@link TestResultState.Pending} state. - * - * @param request Test run request. Only tests inside the `include` may be - * modified, and tests in its `exclude` are ignored. - * @param name The human-readable name of the run. This can be used to - * disambiguate multiple sets of results in a test run. It is useful if - * tests are run across multiple platforms, for example. - * @param persist Whether the results created by the run should be - * persisted in the editor. This may be false if the results are coming from - * a file already saved externally, such as a coverage information file. - */ - export function createTestRun(request: TestRunRequest, name?: string, persist?: boolean): TestRun; - - /** - * Creates a new managed {@link TestItem} instance. - * @param options Initial/required options for the item - * @param data Custom data to be stored in {@link TestItem.data} + * Returns an observer that watches and can request tests. */ - export function createTestItem(options: TestItemOptions, data: T): TestItem; - - /** - * Creates a new managed {@link TestItem} instance. - * @param options Initial/required options for the item - */ - export function createTestItem(options: TestItemOptions): TestItem; - + export function createTestObserver(): TestObserver; /** * List of test results stored by the editor, sorted in descending * order by their `completedAt` time. - * @stability experimental */ export const testResults: ReadonlyArray; /** * Event that fires when the {@link testResults} array is updated. - * @stability experimental */ export const onDidChangeTestResults: Event; } - /** - * @stability experimental - */ export interface TestObserver { /** * List of tests returned by test provider for files in the workspace. */ - readonly tests: ReadonlyArray>; + readonly tests: ReadonlyArray; /** * An event that fires when an existing test in the collection changes, or @@ -1932,16 +1945,6 @@ declare module 'vscode' { */ readonly onDidChangeTest: Event; - /** - * An event that fires when all test providers have signalled that the tests - * the observer references have been discovered. Providers may continue to - * watch for changes and cause {@link onDidChangeTest} to fire as files - * change, until the observer is disposed. - * - * @todo as below - */ - readonly onDidDiscoverInitialTests: Event; - /** * Dispose of the observer, allowing the editor to eventually tell test * providers that they no longer need to update tests. @@ -1949,424 +1952,73 @@ declare module 'vscode' { dispose(): void; } - /** - * @stability experimental - */ export interface TestsChangeEvent { /** * List of all tests that are newly added. */ - readonly added: ReadonlyArray>; + readonly added: ReadonlyArray; /** * List of existing tests that have updated. */ - readonly updated: ReadonlyArray>; + readonly updated: ReadonlyArray; /** * List of existing tests that have been removed. */ - readonly removed: ReadonlyArray>; + readonly removed: ReadonlyArray; } /** - * Interface to discover and execute tests. + * 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 TestController { - /** - * Requests that tests be provided for the given workspace. This will - * be called when tests need to be enumerated for the workspace, such as - * when the user opens the test explorer. - * - * It's guaranteed that this method will not be called again while - * there is a previous uncancelled call for the given workspace folder. - * - * @param workspace The workspace in which to observe tests - * @param cancellationToken Token that signals the used asked to abort the test run. - * @returns the root test item for the workspace - */ - createWorkspaceTestRoot(workspace: WorkspaceFolder, token: CancellationToken): ProviderResult>; - - /** - * Requests that tests be provided for the given document. This will be - * called when tests need to be enumerated for a single open file, for - * instance by code lens UI. - * - * It's suggested that the provider listen to change events for the text - * document to provide information for tests that might not yet be - * saved. - * - * If the test system is not able to provide or estimate for tests on a - * per-file basis, this method may not be implemented. In that case, the - * editor will request and use the information from the workspace tree. - * - * @param document The document in which to observe tests - * @param cancellationToken Token that signals the used asked to abort the test run. - * @returns the root test item for the document - */ - createDocumentTestRoot?(document: TextDocument, token: CancellationToken): ProviderResult>; - + export interface TestItem { /** - * Starts a test run. When called, the controller should call - * {@link vscode.test.createTestRun}. All tasks associated with the - * run should be created before the function returns or the reutrned - * promise is resolved. + * 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. * - * @param options Options for this test run - * @param cancellationToken Token that signals the used asked to abort the test run. + * Extensions should generally not override this method. */ - runTests(options: TestRunRequest, token: CancellationToken): Thenable | void; + // todo@api still unsure about this + invalidateResults(): void; } + /** - * Options given to {@link test.runTests}. + * 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 TestRunRequest { + export interface TestRunResult { /** - * Array of specific tests to run. The controllers should run all of the - * given tests and all children of the given tests, excluding any tests - * that appear in {@link TestRunRequest.exclude}. + * Unix milliseconds timestamp at which the test run was completed. */ - tests: TestItem[]; + readonly completedAt: number; /** - * An array of tests the user has marked as excluded in the editor. May be - * omitted if no exclusions were requested. Test controllers should not run - * excluded tests or any children of excluded tests. + * Optional raw output from the test run. */ - exclude?: TestItem[]; + readonly output?: string; /** - * Whether tests in this run should be debugged. + * List of test results. The items in this array are the items that + * were passed in the {@link tests.runTests} method. */ - debug: boolean; + readonly results: ReadonlyArray>; } /** - * Options given to {@link TestController.runTests} + * A {@link TestItem}-like interface with an associated result, which appear + * or can be provided in {@link TestResult} interfaces. */ - export interface TestRun { - /** - * The human-readable name of the run. This can be used to - * disambiguate multiple sets of results in a test run. It is useful if - * tests are run across multiple platforms, for example. - */ - readonly name?: string; - - /** - * Updates the state of the test in the run. Calling with method with nodes - * outside the {@link TestRunRequest.tests} or in the - * {@link TestRunRequest.exclude} array will no-op. - * - * @param test The test to update - * @param state The state to assign to the test - * @param duration Optionally sets how long the test took to run - */ - setState(test: TestItem, state: TestResultState, duration?: number): void; - - /** - * Appends a message, such as an assertion error, to the test item. - * - * Calling with method with nodes outside the {@link TestRunRequest.tests} - * or in the {@link TestRunRequest.exclude} array will no-op. - * - * @param test The test to update - * @param state The state to assign to the test - * - */ - appendMessage(test: TestItem, message: TestMessage): void; - - /** - * 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 associateTo Optionally, associate the given segment of output - */ - appendOutput(output: string): void; - - /** - * Signals that the end of the test run. Any tests whose states have not - * been updated will be moved into the {@link TestResultState.Unset} state. - */ - end(): void; - } - - /** - * Indicates the the activity state of the {@link TestItem}. - */ - export enum TestItemStatus { - /** - * All children of the test item, if any, have been discovered. - */ - Resolved = 1, - - /** - * The test item may have children who have not been discovered yet. - */ - Pending = 0, - } - - /** - * Options initially passed into `vscode.test.createTestItem` - */ - export interface TestItemOptions { - /** - * Unique identifier for the TestItem. This is used to correlate - * test results and tests in the document with those in the workspace - * (test explorer). This cannot change for the lifetime of the TestItem. - */ - id: string; - - /** - * URI this TestItem is associated with. May be a file or directory. - */ - uri?: Uri; - - /** - * Display name describing the test item. - */ - label: string; - } - - /** - * 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 { - /** - * Unique identifier for the TestItem. This is used to correlate - * test results and tests in the document with those in the workspace - * (test explorer). This must not change for the lifetime of the TestItem. - */ - readonly id: string; - - /** - * URI this TestItem is associated with. May be a file or directory. - */ - readonly uri?: Uri; - - /** - * A mapping of children by ID to the associated TestItem instances. - */ - readonly children: ReadonlyMap>; - - /** - * The parent of this item, if any. Assigned automatically when calling - * {@link TestItem.addChild}. - */ - readonly parent?: TestItem; - - /** - * Indicates the state of the test item's children. The editor will show - * TestItems in the `Pending` state and with a `resolveHandler` as being - * expandable, and will call the `resolveHandler` to request items. - * - * A TestItem in the `Resolved` state is assumed to have discovered and be - * watching for changes in its children if applicable. TestItems are in the - * `Resolved` state when initially created; if the editor should call - * the `resolveHandler` to discover children, set the state to `Pending` - * after creating the item. - */ - status: TestItemStatus; - - /** - * Display name describing the test case. - */ - label: string; - - /** - * Optional description that appears next to the label. - */ - description?: string; - - /** - * Location of the test item in its `uri`. This is only meaningful if the - * `uri` points to a file. - */ - range?: Range; - - /** - * May be set to an error associated with loading the test. Note that this - * is not a test result and should only be used to represent errors in - * discovery, such as syntax errors. - */ - error?: string | MarkdownString; - - /** - * Whether this test item can be run by providing it in the - * {@link TestRunRequest.tests} array. Defaults to `true`. - */ - runnable: boolean; - - /** - * Whether this test item can be debugged by providing it in the - * {@link TestRunRequest.tests} array. Defaults to `false`. - */ - debuggable: boolean; - - /** - * Custom extension data on the item. This data will never be serialized - * or shared outside the extenion who created the item. - */ - data: T; - - /** - * 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. - */ - invalidate(): void; - - /** - * A function provided by the extension that the editor may call to request - * children of the item, if the {@link TestItem.status} is `Pending`. - * - * When called, the item should discover tests and call {@link TestItem.addChild}. - * The items should set its {@link TestItem.status} to `Resolved` when - * discovery is finished. - * - * The item should continue watching for changes to the children and - * firing updates until the token is cancelled. The process of watching - * the tests may involve creating a file watcher, for example. After the - * token is cancelled and watching stops, the TestItem should set its - * {@link TestItem.status} back to `Pending`. - * - * The editor will only call this method when it's interested in refreshing - * the children of the item, and will not call it again while there's an - * existing, uncancelled discovery for an item. - * - * @param token Cancellation for the request. Cancellation will be - * requested if the test changes before the previous call completes. - */ - resolveHandler?: (token: CancellationToken) => void; - - /** - * Attaches a child, created from the {@link test.createTestItem} function, - * to this item. A `TestItem` may be a child of at most one other item. - */ - addChild(child: TestItem): void; - - /** - * Removes the test and its children from the tree. Any tokens passed to - * child `resolveHandler` methods will be cancelled. - */ - dispose(): void; - } - - /** - * Possible states of tests in a test run. - */ - export enum TestResultState { - // Initial state - Unset = 0, - // 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 - } - - /** - * Represents the severity of test messages. - */ - export enum TestMessageSeverity { - Error = 0, - Warning = 1, - Information = 2, - Hint = 3 - } - - /** - * Message associated with the test state. Can be linked to a specific - * source range -- useful for assertion failures, for example. - */ - export class TestMessage { - /** - * Human-readable message text to display. - */ - message: string | MarkdownString; - - /** - * Message severity. Defaults to "Error". - */ - severity: TestMessageSeverity; - - /** - * Expected test output. If given with `actualOutput`, a diff view will be shown. - */ - expectedOutput?: string; - - /** - * Actual test output. If given with `expectedOutput`, a diff view will be shown. - */ - actualOutput?: string; - - /** - * Associated file location. - */ - location?: Location; - - /** - * Creates a new TestMessage that will present as a diff in the editor. - * @param message Message to display to the user. - * @param expected Expected output. - * @param actual Actual output. - */ - static diff(message: string | MarkdownString, expected: string, actual: string): TestMessage; - - /** - * Creates a new TestMessage instance. - * @param message The message to show to the user. - */ - constructor(message: string | MarkdownString); - } - - /** - * TestResults can be provided to the editor in {@link test.publishTestResult}, - * or read from it in {@link test.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. - * - * @todo coverage and other info may eventually be provided here - */ - export interface TestRunResult { - /** - * Unix milliseconds timestamp at which the test run was completed. - */ - completedAt: number; - - /** - * Optional raw output from the test run. - */ - output?: string; - - /** - * List of test results. The items in this array are the items that - * were passed in the {@link test.runTests} method. - */ - results: ReadonlyArray>; - } - - /** - * A {@link TestItem}-like interface with an associated result, which appear - * or can be provided in {@link TestResult} interfaces. - */ - export interface TestResultSnapshot { + 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 @@ -2374,6 +2026,11 @@ declare module 'vscode' { */ readonly id: string; + /** + * Parent of this item. + */ + readonly parent?: TestResultSnapshot; + /** * URI this TestItem is associated with. May be a file or file. */ @@ -2399,7 +2056,7 @@ declare module 'vscode' { * 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; + readonly taskStates: ReadonlyArray; /** * Optional list of nested tests for this item. @@ -2407,7 +2064,7 @@ declare module 'vscode' { readonly children: Readonly[]; } - export interface TestSnapshoptTaskState { + export interface TestSnapshotTaskState { /** * Current result of the test. */ @@ -2426,6 +2083,24 @@ declare module 'vscode' { 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) @@ -2586,83 +2261,67 @@ declare module 'vscode' { //#endregion - //#region @joaomoreno https://github.com/microsoft/vscode/issues/124263 - // This API change only affects behavior and documentation, not API surface. + //#region https://github.com/Microsoft/vscode/issues/15178 - namespace env { + /** + * Represents a tab within the window + */ + export interface Tab { + /** + * The text displayed on the tab + */ + readonly label: string; /** - * Resolves a uri to form that is accessible externally. - * - * #### `http:` or `https:` scheme - * - * Resolves an *external* uri, such as a `http:` or `https:` link, from where the extension is running to a - * uri to the same resource on the client machine. - * - * This is a no-op if the extension is running on the client machine. - * - * If the extension is running remotely, this function automatically establishes a port forwarding tunnel - * from the local machine to `target` on the remote and returns a local uri to the tunnel. The lifetime of - * the port forwarding tunnel is managed by the editor and the tunnel can be closed by the user. - * - * *Note* that uris passed through `openExternal` are automatically resolved and you should not call `asExternalUri` on them. - * - * #### `vscode.env.uriScheme` - * - * Creates a uri that - if opened in a browser (e.g. via `openExternal`) - will result in a registered {@link UriHandler} - * to trigger. - * - * Extensions should not make any assumptions about the resulting uri and should not alter it in anyway. - * Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query - * argument to the server to authenticate to. - * - * *Note* that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it - * will appear in the uri that is passed to the {@link UriHandler}. - * - * **Example** of an authentication flow: - * ```typescript - * vscode.window.registerUriHandler({ - * handleUri(uri: vscode.Uri): vscode.ProviderResult { - * if (uri.path === '/did-authenticate') { - * console.log(uri.toString()); - * } - * } - * }); - * - * const callableUri = await vscode.env.asExternalUri(vscode.Uri.parse(`${vscode.env.uriScheme}://my.extension/did-authenticate`)); - * await vscode.env.openExternal(callableUri); - * ``` - * - * *Note* that extensions should not cache the result of `asExternalUri` as the resolved uri may become invalid due to - * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by - * `asExternalUri`. - * - * #### Any other scheme - * - * Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return - * a URI which, when handled, will make the editor open the workspace. - * - * @return A uri that can be used on the client machine. + * The position of the tab */ - export function asExternalUri(target: Uri): Thenable; - } + readonly viewColumn: ViewColumn; - //#endregion + /** + * The resource represented by the tab if availble. + * Note: Not all tabs have a resource associated with them. + */ + readonly resource?: Uri; - //#region https://github.com/Microsoft/vscode/issues/15178 + /** + * The identifier of the view contained in the tab + * This is equivalent to `viewType` for custom editors and `notebookType` for notebooks. + * The built-in text editor has an id of 'default' for all configurations. + */ + readonly viewId?: string; - // TODO@API must be a class - export interface OpenEditorInfo { - name: string; - resource: Uri; - isActive: boolean; + /** + * Whether or not the tab is currently active + * Dictated by being the selected tab in the active group + */ + readonly isActive: boolean; } export namespace window { - export const openEditors: ReadonlyArray; + /** + * 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; - // todo@API proper event type - export const onDidChangeOpenEditors: Event; } //#endregion @@ -2697,7 +2356,8 @@ declare module 'vscode' { OpenBrowser = 2, OpenPreview = 3, Silent = 4, - Ignore = 5 + Ignore = 5, + OpenBrowserOnce = 6 } export class PortAttributes { @@ -2781,6 +2441,25 @@ declare module 'vscode' { * 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; } /** @@ -2808,9 +2487,9 @@ declare module 'vscode' { export class InlineCompletionItem { /** - * The text to insert. - * If the text contains a line break, the range must end at the end of a line. - * If existing text should be replaced, the existing text must be a prefix of the text to insert. + * 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; @@ -2818,8 +2497,8 @@ declare module 'vscode' { * 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 extends a word, + * 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; @@ -2860,43 +2539,279 @@ declare module 'vscode' { //#endregion - //#region FileSystemProvider stat readonly - https://github.com/microsoft/vscode/issues/73122 + //#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 enum FilePermission { + export interface NotebookCell { /** - * The file is readonly. + * Mime type determines how the markup cell's `value` is interpreted. + * + * The mime selects which notebook renders is used to render the cell. * - * *Note:* All `FileStat` from a `FileSystemProvider` that is registered with - * the option `isReadonly: true` will be implicitly handled as if `FilePermission.Readonly` - * is set. As a consequence, it is not possible to have a readonly file system provider - * registered where some `FileStat` are not readonly. + * 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. */ - Readonly = 1 + coverageProvider?: TestCoverageProvider + // ... } /** - * The `FileStat`-type represents metadata about a file + * 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 FileStat { + 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; /** - * The permissions of the file, e.g. whether the file is readonly. + * 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. * - * *Note:* This value might be a bitmask, e.g. `FilePermission.Readonly | FilePermission.Other`. + * @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. */ - permissions?: FilePermission; + 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/87110 @eamodio + //#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; + } - export interface Memento { + 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 + + //#region @mjbvz https://github.com/microsoft/vscode/issues/40607 + export interface MarkdownString { /** - * The stored keys. + * Indicates that this markdown string can contain raw html tags. Default to false. + * + * When `supportHtml` is false, the markdown renderer will strip out any raw html tags + * that appear in the markdown text. This means you can only use markdown syntax for rendering. + * + * When `supportHtml` is true, the markdown render will also allow a safe subset of html tags + * and attributes to be rendered. See https://github.com/microsoft/vscode/blob/6d2920473c6f13759c978dd89104c4270a83422d/src/vs/base/browser/markdownRenderer.ts#L296 + * for a list of all supported tags and attributes. */ - readonly keys: readonly string[]; + supportHtml?: boolean; } //#endregion