From b8f6ad3b2f22e00bf855a38d4abe67a0d836b158 Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 19 May 2021 13:35:34 -0700 Subject: [PATCH 01/11] update proposed API --- .../common/experiments/service.unit.test.ts | 4 +- src/test/mocks/mementos.ts | 11 +- types/vscode.proposed.d.ts | 6583 +++++++++-------- 3 files changed, 3338 insertions(+), 3260 deletions(-) diff --git a/src/test/common/experiments/service.unit.test.ts b/src/test/common/experiments/service.unit.test.ts index 41520509de3..5857e493822 100644 --- a/src/test/common/experiments/service.unit.test.ts +++ b/src/test/common/experiments/service.unit.test.ts @@ -181,14 +181,14 @@ suite('Experimentation service', () => { suite('In-experiment check', () => { // eslint-disable-next-line @typescript-eslint/no-explicit-any const experiment: any = 'Test Experiment - experiment'; - let telemetryEvents: { eventName: string; properties: object }[] = []; + let telemetryEvents: { eventName: string; properties: object | undefined }[] = []; let isCachedFlightEnabledStub: sinon.SinonStub; let sendTelemetryEventStub: sinon.SinonStub; setup(() => { sendTelemetryEventStub = sinon .stub(Telemetry, 'sendTelemetryEvent') - .callsFake((eventName: string, _, properties: object) => { + .callsFake((eventName: string, _, properties: object | undefined) => { const telemetry = { eventName, properties }; telemetryEvents.push(telemetry); }); diff --git a/src/test/mocks/mementos.ts b/src/test/mocks/mementos.ts index 354232c16ce..08a9a6ced98 100644 --- a/src/test/mocks/mementos.ts +++ b/src/test/mocks/mementos.ts @@ -7,6 +7,7 @@ export class MockMemento implements Memento { // what VS code has for a memento. We use this to eliminate a bad bug // with writing too much data to global storage. See bug https://github.com/microsoft/vscode-python/issues/9159 private _value: Record = {}; + private _keys: string[] = []; public get(key: string, defaultValue?: T): T { const exists = this._value.hasOwnProperty(key); // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -20,7 +21,15 @@ export class MockMemento implements Memento { public clear() { this._value = {}; } - public setKeysForSync(_keys: string[]): void { + public setKeysForSync(keys: string[]): void { // noop. + this._keys = keys; } + /** + * The stored keys. + */ + public get keys(): readonly string[] { + return this._keys; + } + // IANHU: Not sure if this is right. Just focusing on the notebook related BC } diff --git a/types/vscode.proposed.d.ts b/types/vscode.proposed.d.ts index 8b77f25f7c0..16b6b7e85fd 100644 --- a/types/vscode.proposed.d.ts +++ b/types/vscode.proposed.d.ts @@ -16,3261 +16,3330 @@ 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 - - export interface MessageOptions { - /** - * Do not render a native message box. - */ - useCustom?: boolean; - } - - export interface RemoteAuthorityResolverContext { - resolveAttempt: number; - } - - export class ResolvedAuthority { - readonly host: string; - readonly port: number; - readonly connectionToken: string | undefined; - - constructor(host: string, port: number, connectionToken?: string); - } - - export enum RemoteTrustOption { - Unknown = 0, - DisableTrust = 1, - MachineTrusted = 2 - } - - export interface ResolvedOptions { - extensionHostEnv?: { [key: string]: string | null; }; - - trust?: RemoteTrustOption; - } - - export interface TunnelOptions { - remoteAddress: { port: number, host: string; }; - // The desired local port. If this port can't be used, then another will be chosen. - localAddressPort?: number; - label?: string; - public?: boolean; - } - - export interface TunnelDescription { - remoteAddress: { port: number, host: string; }; - //The complete local address(ex. localhost:1234) - localAddress: { port: number, host: string; } | string; - public?: boolean; - } - - export interface Tunnel extends TunnelDescription { - // Implementers of Tunnel should fire onDidDispose when dispose is called. - onDidDispose: Event; - dispose(): void | Thenable; - } - - /** - * Used as part of the ResolverResult if the extension has any candidate, - * published, or forwarded ports. - */ - export interface TunnelInformation { - /** - * Tunnels that are detected by the extension. The remotePort is used for display purposes. - * The localAddress should be the complete local address (ex. localhost:1234) for connecting to the port. Tunnels provided through - * detected are read-only from the forwarded ports UI. - */ - environmentTunnels?: TunnelDescription[]; - - } - - export interface TunnelCreationOptions { - /** - * True when the local operating system will require elevation to use the requested local port. - */ - elevationRequired?: boolean; - } - - export enum CandidatePortSource { - None = 0, - Process = 1, - Output = 2 - } - - export type ResolverResult = ResolvedAuthority & ResolvedOptions & TunnelInformation; - - export class RemoteAuthorityResolverError extends Error { - static NotAvailable(message?: string, handled?: boolean): RemoteAuthorityResolverError; - static TemporarilyNotAvailable(message?: string): RemoteAuthorityResolverError; - - constructor(message?: string); - } - - export interface RemoteAuthorityResolver { - resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable; - /** - * Can be optionally implemented if the extension can forward ports better than the core. - * When not implemented, the core will use its default forwarding logic. - * When implemented, the core will use this to forward ports. - * - * To enable the "Change Local Port" action on forwarded ports, make sure to set the `localAddress` of - * the returned `Tunnel` to a `{ port: number, host: string; }` and not a string. - */ - tunnelFactory?: (tunnelOptions: TunnelOptions, tunnelCreationOptions: TunnelCreationOptions) => Thenable | undefined; - - /**p - * Provides filtering for candidate ports. - */ - showCandidatePort?: (host: string, port: number, detail: string) => Thenable; - - /** - * Lets the resolver declare which tunnel factory features it supports. - * UNDER DISCUSSION! MAY CHANGE SOON. - */ - tunnelFeatures?: { - elevation: boolean; - public: boolean; - }; - - candidatePortSource?: CandidatePortSource; - } - - export namespace workspace { - /** - * Forwards a port. If the current resolver implements RemoteAuthorityResolver:forwardPort then that will be used to make the tunnel. - * By default, openTunnel only support localhost; however, RemoteAuthorityResolver:tunnelFactory can be used to support other ips. - * - * @throws When run in an environment without a remote. - * - * @param tunnelOptions The `localPort` is a suggestion only. If that port is not available another will be chosen. - */ - export function openTunnel(tunnelOptions: TunnelOptions): Thenable; - - /** - * Gets an array of the currently available tunnels. This does not include environment tunnels, only tunnels that have been created by the user. - * Note that these are of type TunnelDescription and cannot be disposed. - */ - export let tunnels: Thenable; - - /** - * Fired when the list of tunnels has changed. - */ - export const onDidChangeTunnels: Event; - } - - export interface ResourceLabelFormatter { - scheme: string; - authority?: string; - formatting: ResourceLabelFormatting; - } - - export interface ResourceLabelFormatting { - label: string; // myLabel:/${path} - // For historic reasons we use an or string here. Once we finalize this API we should start using enums instead and adopt it in extensions. - // eslint-disable-next-line vscode-dts-literal-or-types - separator: '/' | '\\' | ''; - tildify?: boolean; - normalizeDriveLetter?: boolean; - workspaceSuffix?: string; - authorityPrefix?: string; - stripPathStartingSeparator?: boolean; - } - - export namespace workspace { - export function registerRemoteAuthorityResolver(authorityPrefix: string, resolver: RemoteAuthorityResolver): Disposable; - export function registerResourceLabelFormatter(formatter: ResourceLabelFormatter): Disposable; - } - - //#endregion - - //#region editor insets: https://github.com/microsoft/vscode/issues/85682 - - export interface WebviewEditorInset { - readonly editor: TextEditor; - readonly line: number; - readonly height: number; - readonly webview: Webview; - readonly onDidDispose: Event; - dispose(): void; - } - - export namespace window { - export function createWebviewTextEditorInset(editor: TextEditor, line: number, height: number, options?: WebviewOptions): WebviewEditorInset; - } - - //#endregion - - //#region read/write in chunks: https://github.com/microsoft/vscode/issues/84515 - - export interface FileSystemProvider { - open?(resource: Uri, options: { create: boolean; }): number | Thenable; - close?(fd: number): void | Thenable; - read?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable; - write?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable; - } - - //#endregion - - //#region TextSearchProvider: https://github.com/microsoft/vscode/issues/59921 - - /** - * The parameters of a query for text search. - */ - export interface TextSearchQuery { - /** - * The text pattern to search for. - */ - pattern: string; - - /** - * Whether or not `pattern` should match multiple lines of text. - */ - isMultiline?: boolean; - - /** - * Whether or not `pattern` should be interpreted as a regular expression. - */ - isRegExp?: boolean; - - /** - * Whether or not the search should be case-sensitive. - */ - isCaseSensitive?: boolean; - - /** - * Whether or not to search for whole word matches only. - */ - isWordMatch?: boolean; - } - - /** - * A file glob pattern to match file paths against. - * TODO@roblourens merge this with the GlobPattern docs/definition in vscode.d.ts. - * @see {@link GlobPattern} - */ - export type GlobString = string; - - /** - * Options common to file and text search - */ - export interface SearchOptions { - /** - * The root folder to search within. - */ - folder: Uri; - - /** - * Files that match an `includes` glob pattern should be included in the search. - */ - includes: GlobString[]; - - /** - * Files that match an `excludes` glob pattern should be excluded from the search. - */ - excludes: GlobString[]; - - /** - * Whether external files that exclude files, like .gitignore, should be respected. - * See the vscode setting `"search.useIgnoreFiles"`. - */ - useIgnoreFiles: boolean; - - /** - * Whether symlinks should be followed while searching. - * See the vscode setting `"search.followSymlinks"`. - */ - followSymlinks: boolean; - - /** - * Whether global files that exclude files, like .gitignore, should be respected. - * See the vscode setting `"search.useGlobalIgnoreFiles"`. - */ - useGlobalIgnoreFiles: boolean; - } - - /** - * Options to specify the size of the result text preview. - * These options don't affect the size of the match itself, just the amount of preview text. - */ - export interface TextSearchPreviewOptions { - /** - * The maximum number of lines in the preview. - * Only search providers that support multiline search will ever return more than one line in the match. - */ - matchLines: number; - - /** - * The maximum number of characters included per line. - */ - charsPerLine: number; - } - - /** - * Options that apply to text search. - */ - export interface TextSearchOptions extends SearchOptions { - /** - * The maximum number of results to be returned. - */ - maxResults: number; - - /** - * Options to specify the size of the result text preview. - */ - previewOptions?: TextSearchPreviewOptions; - - /** - * Exclude files larger than `maxFileSize` in bytes. - */ - maxFileSize?: number; - - /** - * Interpret files using this encoding. - * See the vscode setting `"files.encoding"` - */ - encoding?: string; - - /** - * Number of lines of context to include before each match. - */ - beforeContext?: number; - - /** - * Number of lines of context to include after each match. - */ - afterContext?: number; - } - - /** - * Represents the severiry of a TextSearchComplete message. - */ - export enum TextSearchCompleteMessageType { - Information = 1, - Warning = 2, - } - - /** - * Information collected when text search is complete. - */ - export interface TextSearchComplete { - /** - * Whether the search hit the limit on the maximum number of search results. - * `maxResults` on {@link TextSearchOptions `TextSearchOptions`} specifies the max number of results. - * - If exactly that number of matches exist, this should be false. - * - If `maxResults` matches are returned and more exist, this should be true. - * - If search hits an internal limit which is less than `maxResults`, this should be true. - */ - limitHit?: boolean; - - /** - * Additional information regarding the state of the completed search. - * - * Messages with "Information" tyle support links in markdown syntax: - * - Click to [run a command](command:workbench.action.OpenQuickPick) - * - Click to [open a website](https://aka.ms) - */ - message?: { text: string, type: TextSearchCompleteMessageType } | { text: string, type: TextSearchCompleteMessageType }[]; - } - - /** - * A preview of the text result. - */ - export interface TextSearchMatchPreview { - /** - * The matching lines of text, or a portion of the matching line that contains the match. - */ - text: string; - - /** - * The Range within `text` corresponding to the text of the match. - * The number of matches must match the TextSearchMatch's range property. - */ - matches: Range | Range[]; - } - - /** - * A match from a text search - */ - export interface TextSearchMatch { - /** - * The uri for the matching document. - */ - uri: Uri; - - /** - * The range of the match within the document, or multiple ranges for multiple matches. - */ - ranges: Range | Range[]; - - /** - * A preview of the text match. - */ - preview: TextSearchMatchPreview; - } - - /** - * A line of context surrounding a TextSearchMatch. - */ - export interface TextSearchContext { - /** - * The uri for the matching document. - */ - uri: Uri; - - /** - * One line of text. - * previewOptions.charsPerLine applies to this - */ - text: string; - - /** - * The line number of this line of context. - */ - lineNumber: number; - } - - export type TextSearchResult = TextSearchMatch | TextSearchContext; - - /** - * A TextSearchProvider provides search results for text results inside files in the workspace. - */ - export interface TextSearchProvider { - /** - * Provide results that match the given text pattern. - * @param query The parameters for this query. - * @param options A set of options to consider while searching. - * @param progress A progress callback that must be invoked for all results. - * @param token A cancellation token. - */ - provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress, token: CancellationToken): ProviderResult; - } - - //#endregion - - //#region FileSearchProvider: https://github.com/microsoft/vscode/issues/73524 - - /** - * The parameters of a query for file search. - */ - export interface FileSearchQuery { - /** - * The search pattern to match against file paths. - */ - pattern: string; - } - - /** - * Options that apply to file search. - */ - export interface FileSearchOptions extends SearchOptions { - /** - * The maximum number of results to be returned. - */ - maxResults?: number; - - /** - * A CancellationToken that represents the session for this search query. If the provider chooses to, this object can be used as the key for a cache, - * and searches with the same session object can search the same cache. When the token is cancelled, the session is complete and the cache can be cleared. - */ - session?: CancellationToken; - } - - /** - * A FileSearchProvider provides search results for files in the given folder that match a query string. It can be invoked by quickopen or other extensions. - * - * A FileSearchProvider is the more powerful of two ways to implement file search in VS Code. Use a FileSearchProvider if you wish to search within a folder for - * all files that match the user's query. - * - * The FileSearchProvider will be invoked on every keypress in quickopen. When `workspace.findFiles` is called, it will be invoked with an empty query string, - * and in that case, every file in the folder should be returned. - */ - export interface FileSearchProvider { - /** - * Provide the set of files that match a certain file path pattern. - * @param query The parameters for this query. - * @param options A set of options to consider while searching files. - * @param token A cancellation token. - */ - provideFileSearchResults(query: FileSearchQuery, options: FileSearchOptions, token: CancellationToken): ProviderResult; - } - - export namespace workspace { - /** - * Register a search provider. - * - * Only one provider can be registered per scheme. - * - * @param scheme The provider will be invoked for workspace folders that have this file scheme. - * @param provider The provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. - */ - export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable; - - /** - * Register a text search provider. - * - * Only one provider can be registered per scheme. - * - * @param scheme The provider will be invoked for workspace folders that have this file scheme. - * @param provider The provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. - */ - export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable; - } - - //#endregion - - //#region findTextInFiles: https://github.com/microsoft/vscode/issues/59924 - - /** - * Options that can be set on a findTextInFiles search. - */ - export interface FindTextInFilesOptions { - /** - * A {@link GlobPattern glob pattern} that defines the files to search for. The glob pattern - * will be matched against the file paths of files relative to their workspace. Use a {@link RelativePattern relative pattern} - * to restrict the search results to a {@link WorkspaceFolder workspace folder}. - */ - include?: GlobPattern; - - /** - * A {@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern - * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes will - * apply. - */ - exclude?: GlobPattern; - - /** - * Whether to use the default and user-configured excludes. Defaults to true. - */ - useDefaultExcludes?: boolean; - - /** - * The maximum number of results to search for - */ - maxResults?: number; - - /** - * Whether external files that exclude files, like .gitignore, should be respected. - * See the vscode setting `"search.useIgnoreFiles"`. - */ - useIgnoreFiles?: boolean; - - /** - * Whether global files that exclude files, like .gitignore, should be respected. - * See the vscode setting `"search.useGlobalIgnoreFiles"`. - */ - useGlobalIgnoreFiles?: boolean; - - /** - * Whether symlinks should be followed while searching. - * See the vscode setting `"search.followSymlinks"`. - */ - followSymlinks?: boolean; - - /** - * Interpret files using this encoding. - * See the vscode setting `"files.encoding"` - */ - encoding?: string; - - /** - * Options to specify the size of the result text preview. - */ - previewOptions?: TextSearchPreviewOptions; - - /** - * Number of lines of context to include before each match. - */ - beforeContext?: number; - - /** - * Number of lines of context to include after each match. - */ - afterContext?: number; - } - - export namespace workspace { - /** - * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. - * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. - * @param callback A callback, called for each result - * @param token A token that can be used to signal cancellation to the underlying search engine. - * @return A thenable that resolves when the search is complete. - */ - export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; - - /** - * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. - * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. - * @param options An optional set of query options. Include and exclude patterns, maxResults, etc. - * @param callback A callback, called for each result - * @param token A token that can be used to signal cancellation to the underlying search engine. - * @return A thenable that resolves when the search is complete. - */ - export function findTextInFiles(query: TextSearchQuery, options: FindTextInFilesOptions, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; - } - - //#endregion - - //#region diff command: https://github.com/microsoft/vscode/issues/84899 - - /** - * The contiguous set of modified lines in a diff. - */ - export interface LineChange { - readonly originalStartLineNumber: number; - readonly originalEndLineNumber: number; - readonly modifiedStartLineNumber: number; - readonly modifiedEndLineNumber: number; - } - - export namespace commands { - - /** - * Registers a diff information command that can be invoked via a keyboard shortcut, - * a menu item, an action, or directly. - * - * Diff information commands are different from ordinary {@link commands.registerCommand commands} as - * they only execute when there is an active diff editor when the command is called, and the diff - * information has been computed. Also, the command handler of an editor command has access to - * the diff information. - * - * @param command A unique identifier for the command. - * @param callback A command handler function with access to the {@link LineChange diff information}. - * @param thisArg The `this` context used when invoking the handler function. - * @return Disposable which unregisters this command on disposal. - */ - export function registerDiffInformationCommand(command: string, callback: (diff: LineChange[], ...args: any[]) => any, thisArg?: any): Disposable; - } - - //#endregion - - // eslint-disable-next-line vscode-dts-region-comments - //#region @weinand: variables view action contributions - - /** - * A DebugProtocolVariableContainer is an opaque stand-in type for the intersection of the Scope and Variable types defined in the Debug Adapter Protocol. - * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Scope and https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. - */ - export interface DebugProtocolVariableContainer { - // Properties: the intersection of DAP's Scope and Variable types. - } - - /** - * A DebugProtocolVariable is an opaque stand-in type for the Variable type defined in the Debug Adapter Protocol. - * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. - */ - export interface DebugProtocolVariable { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Variable). - } - - //#endregion - - // eslint-disable-next-line vscode-dts-region-comments - //#region @joaomoreno: SCM validation - - /** - * Represents the validation type of the Source Control input. - */ - export enum SourceControlInputBoxValidationType { - - /** - * Something not allowed by the rules of a language or other means. - */ - Error = 0, - - /** - * Something suspicious but allowed. - */ - Warning = 1, - - /** - * Something to inform about but not a problem. - */ - Information = 2 - } - - export interface SourceControlInputBoxValidation { - - /** - * The validation message to display. - */ - readonly message: string; - - /** - * The validation type. - */ - readonly type: SourceControlInputBoxValidationType; - } - - /** - * Represents the input box in the Source Control viewlet. - */ - export interface SourceControlInputBox { - - /** - * Shows a transient contextual message on the input. - */ - showValidationMessage(message: string, type: SourceControlInputBoxValidationType): void; - - /** - * A validation function for the input box. It's possible to change - * the validation provider simply by setting this property to a different function. - */ - validateInput?(value: string, cursorPosition: number): ProviderResult; - } - - //#endregion - - // eslint-disable-next-line vscode-dts-region-comments - //#region @joaomoreno: SCM selected provider - - export interface SourceControl { - - /** - * Whether the source control is selected. - */ - readonly selected: boolean; - - /** - * An event signaling when the selection state changes. - */ - readonly onDidChangeSelection: Event; - } - - //#endregion - - //#region Terminal data write event https://github.com/microsoft/vscode/issues/78502 - - export interface TerminalDataWriteEvent { - /** - * The {@link Terminal} for which the data was written. - */ - readonly terminal: Terminal; - /** - * The data being written. - */ - readonly data: string; - } - - namespace window { - /** - * An event which fires when the terminal's child pseudo-device is written to (the shell). - * In other words, this provides access to the raw data stream from the process running - * within the terminal, including VT sequences. - */ - export const onDidWriteTerminalData: Event; - } - - //#endregion - - //#region Terminal dimensions property and change event https://github.com/microsoft/vscode/issues/55718 - - /** - * An {@link Event} which fires when a {@link Terminal}'s dimensions change. - */ - export interface TerminalDimensionsChangeEvent { - /** - * The {@link Terminal} for which the dimensions have changed. - */ - readonly terminal: Terminal; - /** - * The new value for the {@link Terminal.dimensions terminal's dimensions}. - */ - readonly dimensions: TerminalDimensions; - } - - export namespace window { - /** - * An event which fires when the {@link Terminal.dimensions dimensions} of the terminal change. - */ - export const onDidChangeTerminalDimensions: Event; - } - - export interface Terminal { - /** - * The current dimensions of the terminal. This will be `undefined` immediately after the - * terminal is created as the dimensions are not known until shortly after the terminal is - * created. - */ - readonly dimensions: TerminalDimensions | undefined; - } - - //#endregion - - //#region Terminal name change event https://github.com/microsoft/vscode/issues/114898 - - export interface Pseudoterminal { - /** - * An event that when fired allows changing the name of the terminal. - * - * **Example:** Change the terminal name to "My new terminal". - * ```typescript - * const writeEmitter = new vscode.EventEmitter(); - * const changeNameEmitter = new vscode.EventEmitter(); - * const pty: vscode.Pseudoterminal = { - * onDidWrite: writeEmitter.event, - * onDidChangeName: changeNameEmitter.event, - * open: () => changeNameEmitter.fire('My new terminal'), - * close: () => {} - * }; - * vscode.window.createTerminal({ name: 'My terminal', pty }); - * ``` - */ - onDidChangeName?: Event; - } - - //#endregion - - //#region Terminal icon https://github.com/microsoft/vscode/issues/120538 - - export interface TerminalOptions { - /** - * A codicon ID to associate with this terminal. - */ - readonly icon?: string; - } - - //#endregion - - // eslint-disable-next-line vscode-dts-region-comments - //#region @jrieken -> exclusive document filters - - export interface DocumentFilter { - readonly exclusive?: boolean; - } - - //#endregion - - //#region Tree View: https://github.com/microsoft/vscode/issues/61313 @alexr00 - export interface TreeView extends Disposable { - reveal(element: T | undefined, options?: { select?: boolean, focus?: boolean, expand?: boolean | number; }): Thenable; - } - //#endregion - - //#region Custom Tree View Drag and Drop https://github.com/microsoft/vscode/issues/32592 - export interface TreeViewOptions { - /** - * * Whether the tree supports drag and drop. - */ - canDragAndDrop?: boolean; - } - - export interface TreeDataProvider { - /** - * Optional method to reparent an `element`. - * - * **NOTE:** This method should be implemented if the tree supports drag and drop. - * - * @param elements The selected elements that will be reparented. - * @param targetElement The new parent of the elements. - */ - setParent?(elements: T[], targetElement: T): Thenable; - } - - //#endregion - - //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 - export interface TaskPresentationOptions { - /** - * Controls whether the task is executed in a specific terminal group using split panes. - */ - group?: string; - } - //#endregion - - //#region Status bar item with ID and Name: https://github.com/microsoft/vscode/issues/74972 - - /** - * Options to configure the status bar item. - */ - export interface StatusBarItemOptions { - - /** - * A unique identifier of the status bar item. The identifier - * is for example used to allow a user to show or hide the - * status bar item in the UI. - */ - id: string; - - /** - * A human readable name of the status bar item. The name is - * for example used as a label in the UI to show or hide the - * status bar item. - */ - name: string; - - /** - * Accessibility information used when screen reader interacts with this status bar item. - */ - accessibilityInformation?: AccessibilityInformation; - - /** - * The alignment of the status bar item. - */ - alignment?: StatusBarAlignment; - - /** - * The priority of the status bar item. Higher value means the item should - * be shown more to the left. - */ - priority?: number; - } - - export namespace window { - - /** - * Creates a status bar {@link StatusBarItem item}. - * - * @param options The options of the item. If not provided, some default values - * will be assumed. For example, the `StatusBarItemOptions.id` will be the id - * of the extension and the `StatusBarItemOptions.name` will be the extension name. - * @return A new status bar item. - */ - export function createStatusBarItem(options?: StatusBarItemOptions): StatusBarItem; - } - - //#endregion - - //#region Custom editor move https://github.com/microsoft/vscode/issues/86146 - - // TODO: Also for custom editor - - export interface CustomTextEditorProvider { - - /** - * Handle when the underlying resource for a custom editor is renamed. - * - * This allows the webview for the editor be preserved throughout the rename. If this method is not implemented, - * VS Code will destory the previous custom editor and create a replacement one. - * - * @param newDocument New text document to use for the custom editor. - * @param existingWebviewPanel Webview panel for the custom editor. - * @param token A cancellation token that indicates the result is no longer needed. - * - * @return Thenable indicating that the webview editor has been moved. - */ - // eslint-disable-next-line vscode-dts-provider-naming - moveCustomTextEditor?(newDocument: TextDocument, existingWebviewPanel: WebviewPanel, token: CancellationToken): Thenable; - } - - //#endregion - - //#region allow QuickPicks to skip sorting: https://github.com/microsoft/vscode/issues/73904 - - export interface QuickPick extends QuickInput { - /** - * An optional flag to sort the final results by index of first query match in label. Defaults to true. - */ - sortByLabel: boolean; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/122922, Notebook, Finalization 1 - - /** - * A notebook cell kind. - */ - export enum NotebookCellKind { - - /** - * A markup-cell is formatted source that is used for display. - */ - Markup = 1, - - /** - * A code-cell is source that can be {@link NotebookController executed} and that - * produces {@link NotebookCellOutput output}. - */ - Code = 2 - } - - /** - * Represents a cell of a {@link NotebookDocument notebook}, either a {@link NotebookCellKind.Code code}-cell - * or {@link NotebookCellKind.Markup markup}-cell. - * - * NotebookCell instances are immutable and are kept in sync for as long as they are part of their notebook. - */ - // todo@API support ids https://github.com/jupyter/enhancement-proposals/blob/master/62-cell-id/cell-id.md - export interface NotebookCell { - - /** - * The index of this cell in its {@link NotebookDocument.cellAt containing notebook}. The - * index is updated when a cell is moved within its notebook. The index is `-1` - * when the cell has been removed from its notebook. - */ - readonly index: number; - - /** - * The {@link NotebookDocument notebook} that contains this cell. - */ - readonly notebook: NotebookDocument; - - /** - * The kind of this cell. - */ - readonly kind: NotebookCellKind; - - /** - * The {@link TextDocument text} of this cell, represented as text document. - */ - readonly document: TextDocument; - - /** - * The metadata of this cell. - */ - readonly metadata: NotebookCellMetadata - - /** - * The outputs of this cell. - */ - readonly outputs: ReadonlyArray; - - /** - * The most recent {@link NotebookCellExecutionSummary excution summary} for this cell. - */ - readonly executionSummary?: NotebookCellExecutionSummary; - } - - /** - * Represents a notebook which itself is a sequence of {@link NotebookCell code or markup cells}. Notebook documents are - * created from {@link NotebookData notebook data}. - */ - export interface NotebookDocument { - - /** - * The associated uri for this notebook. - * - * *Note* that most notebooks use the `file`-scheme, which means they are files on disk. However, **not** all notebooks are - * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk. - * - * @see {@link FileSystemProvider} - * @see {@link TextDocumentContentProvider} - */ - readonly uri: Uri; - - // todo@API should we really expose this? - // todo@API should this be called `notebookType` or `notebookKind` - readonly viewType: string; - - /** - * The version number of this notebook (it will strictly increase after each - * change, including undo/redo). - */ - readonly version: number; - - /** - * `true` if there are unpersisted changes. - */ - readonly isDirty: boolean; - - /** - * Is this notebook representing an untitled file which has not been saved yet. - */ - readonly isUntitled: boolean; - - /** - * `true` if the notebook has been closed. A closed notebook isn't synchronized anymore - * and won't be re-used when the same resource is opened again. - */ - readonly isClosed: boolean; - - /** - * The {@link NotebookDocumentMetadata metadata} for this notebook. - */ - readonly metadata: NotebookDocumentMetadata; - - /** - * The number of cells in the notebook. - */ - readonly cellCount: number; - - /** - * Return the cell at the specified index. The index will be adjusted to the notebook. - * - * @param index - The index of the cell to retrieve. - * @return A {@link NotebookCell cell}. - */ - cellAt(index: number): NotebookCell; - - /** - * Get the cells of this notebook. A subset can be retrieved by providing - * a range. The range will be adjuset to the notebook. - * - * @param range A notebook range. - * @returns The cells contained by the range or all cells. - */ - getCells(range?: NotebookRange): NotebookCell[]; - - /** - * Save the document. The saving will be handled by the corresponding content provider - * - * @return A promise that will resolve to true when the document - * has been saved. If the file was not dirty or the save failed, - * will return false. - */ - save(): Thenable; - } - - export class NotebookCellMetadata { - /** - * Whether a code cell's editor is collapsed - */ - readonly inputCollapsed?: boolean; - - /** - * Whether a code cell's outputs are collapsed - */ - readonly outputCollapsed?: boolean; - - /** - * Additional attributes of a cell metadata. - */ - readonly [key: string]: any; - - /** - * Create a new notebook cell metadata. - * - * @param inputCollapsed Whether a code cell's editor is collapsed - * @param outputCollapsed Whether a code cell's outputs are collapsed - */ - constructor(inputCollapsed?: boolean, outputCollapsed?: boolean); - - /** - * Derived a new cell metadata from this metadata. - * - * @param change An object that describes a change to this NotebookCellMetadata. - * @return A new NotebookCellMetadata that reflects the given change. Will return `this` NotebookCellMetadata if the change - * is not changing anything. - */ - with(change: { inputCollapsed?: boolean | null, outputCollapsed?: boolean | null, [key: string]: any }): NotebookCellMetadata; - } - - export interface NotebookCellExecutionSummary { - readonly executionOrder?: number; - readonly success?: boolean; - readonly startTime?: number; - readonly endTime?: number; - } - - export class NotebookDocumentMetadata { - /** - * Additional attributes of the document metadata. - */ - readonly [key: string]: any; - - /** - * Create a new notebook document metadata - */ - constructor(); - - /** - * Derived a new document metadata from this metadata. - * - * @param change An object that describes a change to this NotebookDocumentMetadata. - * @return A new NotebookDocumentMetadata that reflects the given change. Will return `this` NotebookDocumentMetadata if the change - * is not changing anything. - */ - with(change: { [key: string]: any }): NotebookDocumentMetadata - } - - /** - * A notebook range represents on ordered pair of two cell indicies. - * It is guaranteed that start is less than or equal to end. - */ - export class NotebookRange { - - /** - * The zero-based start index of this range. - */ - readonly start: number; - - /** - * The exclusive end index of this range (zero-based). - */ - readonly end: number; - - /** - * `true` if `start` and `end` are equal. - */ - readonly isEmpty: boolean; - - /** - * Create a new notebook range. If `start` is not - * before or equal to `end`, the values will be swapped. - * - * @param start start index - * @param end end index. - */ - constructor(start: number, end: number); - - /** - * Derive a new range for this range. - * - * @param change An object that describes a change to this range. - * @return A range that reflects the given change. Will return `this` range if the change - * is not changing anything. - */ - with(change: { start?: number, end?: number }): NotebookRange; - } - - // code specific mime types - // application/x.notebook.error-traceback - // application/x.notebook.stdout - // application/x.notebook.stderr - // application/x.notebook.stream - export class NotebookCellOutputItem { - - // todo@API - // add factory functions for common mime types - // static textplain(value:string): NotebookCellOutputItem; - // static errortrace(value:any): NotebookCellOutputItem; - - /** - * Creates `application/x.notebook.error` - * - * @param err An error for which an output item is wanted - */ - static error(err: Error): NotebookCellOutputItem; - - mime: string; - - //todo@API string or Unit8Array? - // value: string | Uint8Array | unknown; - value: unknown; - - metadata?: { [key: string]: any }; - - constructor(mime: string, value: unknown, metadata?: { [key: string]: any }); - } - - // @jrieken transient - export class NotebookCellOutput { - id: string; - outputs: NotebookCellOutputItem[]; - metadata?: { [key: string]: any }; - constructor(outputs: NotebookCellOutputItem[], metadata?: { [key: string]: any }); - constructor(outputs: NotebookCellOutputItem[], id: string, metadata?: { [key: string]: any }); - } - - /** - * NotebookCellData is the raw representation of notebook cells. Its is part of {@link NotebookData `NotebookData`}. - */ - // todo@API support ids https://github.com/jupyter/enhancement-proposals/blob/master/62-cell-id/cell-id.md - export class NotebookCellData { - - /** - * The {@link NotebookCellKind kind} of this cell data. - */ - kind: NotebookCellKind; - - /** - * The source value of this cell data - either source code or formatted text. - */ - value: string; - - /** - * The language identifier of the source value of this cell data. Any value from - * {@link languages.getLanguages `getLanguages`} is possible. - */ - languageId: string; - - /** - * The outputs of this cell data. - */ - outputs?: NotebookCellOutput[]; - - /** - * The metadata of this cell data. - */ - metadata?: NotebookCellMetadata; - - /** - * The execution summary of this cell data. - */ - executionSummary?: NotebookCellExecutionSummary; - - /** - * Create new cell data. Minimal cell data specifies its kind, its source value, and the - * language identifier of its source. - * - * @param kind The kind. - * @param value The source value. - * @param languageId The language identifier of the source value. - * @param outputs //TODO@API remove ctor? - * @param metadata //TODO@API remove ctor? - * @param executionSummary //TODO@API remove ctor? - */ - constructor(kind: NotebookCellKind, value: string, languageId: string, outputs?: NotebookCellOutput[], metadata?: NotebookCellMetadata, executionSummary?: NotebookCellExecutionSummary); - } - - /** - * NotebookData is the raw representation of notebooks. - * - * Extensions are responsible to create {@link NotebookData `NotebookData`} so that the editor - * can create a {@link NotebookDocument `NotebookDocument`}. - * - * @see {@link NotebookSerializer} - */ - export class NotebookData { - /** - * The cell data of this notebook data. - */ - cells: NotebookCellData[]; - - /** - * The metadata of this notebook data. - */ - metadata: NotebookDocumentMetadata; - - /** - * Create new notebook data. - * - * @param cells An array of cell data. - * @param metadata Notebook metadata. - */ - constructor(cells: NotebookCellData[], metadata?: NotebookDocumentMetadata); - } - - /** - * The notebook serializer enables the editor to open notebook files. - * - * At its core the editor only knows a {@link NotebookData notebook data structure} but not - * how that data structure is written to a file, nor how it is read from a file. The - * notebook serializer bridges this gap by deserializing bytes into notebook data and - * vice versa. - */ - export interface NotebookSerializer { - - /** - * Deserialize contents of a notebook file into the notebook data structure. - * - * @param content Contents of a notebook file. - * @param token A cancellation token. - * @return Notebook data or a thenable that resolves to such. - */ - deserializeNotebook(content: Uint8Array, token: CancellationToken): NotebookData | Thenable; - - /** - * Serialize notebook data into file contents. - * - * @param data A notebook data structure. - * @param token A cancellation token. - * @returns An array of bytes or a thenable that resolves to such. - */ - serializeNotebook(data: NotebookData, token: CancellationToken): Uint8Array | Thenable; - } - - export interface NotebookDocumentContentOptions { - /** - * Controls if outputs change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit the outputs in the file document, this should be set to true. - */ - transientOutputs?: boolean; - - /** - * Controls if a cell metadata property change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. - */ - transientCellMetadata?: { [K in keyof NotebookCellMetadata]?: boolean }; - - /** - * Controls if a document metadata property change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. - */ - transientDocumentMetadata?: { [K in keyof NotebookDocumentMetadata]?: boolean }; - } - - export interface NotebookExecuteHandler { - /** - * @param cells The notebook cells to execute. - * @param notebook The notebook for which the execute handler is being called. - * @param controller The controller that the handler is attached to - */ - (this: NotebookController, cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController): void | Thenable - } - - export interface NotebookInterruptHandler { - /** - * @param notebook The notebook for which the interrupt handler is being called. - */ - (this: NotebookController, notebook: NotebookDocument): void | Thenable; - } - - export enum NotebookControllerAffinity { - Default = 1, - Preferred = 2 - } - - // todo@API this is called Controller - export class NotebookKernelPreload { - /** - * APIs that the preload provides to the renderer. These are matched - * against the `dependencies` and `optionalDependencies` arrays in the - * notebook renderer contribution point. - */ - readonly provides: string[]; - - /** - * URI for the file to preload - */ - readonly uri: Uri; - - /** - * @param uri URI for the file to preload - * @param provides Value for the `provides` property - */ - constructor(uri: Uri, provides?: string | string[]); - } - - export interface NotebookCellExecuteStartContext { - /** - * The time that execution began, in milliseconds in the Unix epoch. Used to drive the clock - * that shows for how long a cell has been running. If not given, the clock won't be shown. - */ - startTime?: number; - } - - export interface NotebookCellExecuteEndContext { - /** - * If true, a green check is shown on the cell status bar. - * If false, a red X is shown. - */ - success?: boolean; - - /** - * The time that execution finished, in milliseconds in the Unix epoch. - */ - endTime?: number; - } - - // todo@API jsdoc slightly outdated: kernel, notebook.createNotebookCellExecutionTask - /** - * A NotebookCellExecutionTask is how the kernel modifies a notebook cell as it is executing. When - * {@link notebook.createNotebookCellExecutionTask `createNotebookCellExecutionTask`} is called, the cell - * enters the Pending state. When `start()` is called on the execution task, it enters the Executing state. When - * `end()` is called, it enters the Idle state. While in the Executing state, cell outputs can be - * modified with the methods on the run task. - * - * All outputs methods operate on this NotebookCellExecutionTask's cell by default. They optionally take - * a cellIndex parameter that allows them to modify the outputs of other cells. `appendOutputItems` and - * `replaceOutputItems` operate on the output with the given ID, which can be an output on any cell. They - * all resolve once the output edit has been applied. - */ - export interface NotebookCellExecutionTask { - readonly document: NotebookDocument; - readonly cell: NotebookCell; - readonly token: CancellationToken; - - start(context?: NotebookCellExecuteStartContext): void; - executionOrder: number | undefined; - end(result?: NotebookCellExecuteEndContext): void; - - clearOutput(cellIndex?: number): Thenable; - appendOutput(out: NotebookCellOutput | NotebookCellOutput[], cellIndex?: number): Thenable; - replaceOutput(out: NotebookCellOutput | NotebookCellOutput[], cellIndex?: number): Thenable; - appendOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], outputId: string): Thenable; - replaceOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], outputId: string): Thenable; - } - - export interface NotebookController { - - /** - * The identifier of this notebook controller. - */ - readonly id: string; - - /** - * The notebook view type this controller is for. - */ - readonly viewType: string; - - /** - * An array of language identifiers that are supported by this - * controller. Any language identifier from {@link languages.getLanguages `getLanguages`} - * is possible. When falsy all languages are supported. - * - * Samples: - * ```js - * // support JavaScript and TypeScript - * myController.supportedLanguages = ['javascript', 'typescript'] - * - * // support all languages - * myController.supportedLanguages = undefined; // falsy - * myController.supportedLanguages = []; // falsy - * ``` - */ - supportedLanguages?: string[]; - - /** - * The human-readable label of this notebook controller. - */ - label: string; - - /** - * The human-readable description which is rendered less prominent. - */ - description?: string; - - /** - * The human-readable detail which is rendered less prominent. - */ - detail?: string; - - /** - * Whether this controller supports execution order so that the - * editor can render placeholders for them. - */ - // todo@API rename to supportsExecutionOrder, usesExecutionOrder - hasExecutionOrder?: boolean; - - /** - * The execute handler is invoked when the run gestures in the UI are selected, e.g Run Cell, Run All, - * Run Selection etc. - */ - executeHandler: NotebookExecuteHandler; - - /** - * The interrupt handler is invoked the interrupt all execution. This is contrary to cancellation (available via - * [`NotebookCellExecutionTask#token`](NotebookCellExecutionTask#token)) and should only be used when - * execution-level cancellation is supported - */ - interruptHandler?: NotebookInterruptHandler - - /** - * Dispose and free associated resources. - */ - dispose(): void; - - /** - * An event that fires whenever a controller has been selected for a notebook document. Selecting a controller - * for a notebook is a user gesture and happens either explicitly or implicitly when interacting while a - * controller was suggested. - */ - readonly onDidChangeNotebookAssociation: Event<{ notebook: NotebookDocument, selected: boolean }>; - - /** - * A controller can set affinities for specific notebook documents. This allows a controller - * to be more important for some notebooks. - * - * @param notebook The notebook for which a priority is set. - * @param affinity A controller affinity - */ - updateNotebookAffinity(notebook: NotebookDocument, affinity: NotebookControllerAffinity): void; - - /** - * Create a cell execution task. - * - * This should be used in response to the {@link NotebookController.executeHandler execution handler} - * being calleed or when cell execution has been started else, e.g when a cell was already - * executing or when cell execution was triggered from another source. - * - * @param cell The notebook cell for which to create the execution. - * @returns A notebook cell execution. - */ - createNotebookCellExecutionTask(cell: NotebookCell): NotebookCellExecutionTask; - - // todo@API find a better name than "preloads" - // todo@API allow add, not remove - // ipc - readonly preloads: NotebookKernelPreload[]; - - /** - * An event that fires when a renderer (see `preloads`) has send a message to the controller. - */ - readonly onDidReceiveMessage: Event<{ editor: NotebookEditor, message: any }>; - - /** - * Send a message to the renderer of notebook editors. - * - * Note that only editors showing documents that are bound to this controller - * are receiving the message. - * - * @param message The message to send. - * @param editor A specific editor to send the message to. When `undefined` all applicable editors are receiving the message. - * @returns A promise that resolves to a boolean indicating if the message has been send or not. - */ - postMessage(message: any, editor?: NotebookEditor): Thenable; - - //todo@API validate this works - asWebviewUri(localResource: Uri): Uri; - } - - export enum NotebookCellExecutionState { - Idle = 1, - Pending = 2, - Executing = 3, - } - - export interface NotebookCellExecutionStateChangeEvent { - /** - * The {@link NotebookDocument notebook document} for which the cell execution state has changed. - */ - readonly document: NotebookDocument; - readonly cell: NotebookCell; - readonly executionState: NotebookCellExecutionState; - } - - /** - * Represents the alignment of status bar items. - */ - export enum NotebookCellStatusBarAlignment { - - /** - * Aligned to the left side. - */ - Left = 1, - - /** - * Aligned to the right side. - */ - Right = 2 - } - - export class NotebookCellStatusBarItem { - text: string; - alignment: NotebookCellStatusBarAlignment; - command?: string | Command; - tooltip?: string; - priority?: number; - accessibilityInformation?: AccessibilityInformation; - - constructor(text: string, alignment: NotebookCellStatusBarAlignment, command?: string | Command, tooltip?: string, priority?: number, accessibilityInformation?: AccessibilityInformation); - } - - export interface NotebookCellStatusBarItemProvider { - /** - * Implement and fire this event to signal that statusbar items have changed. The provide method will be called again. - */ - onDidChangeCellStatusBarItems?: Event; - - /** - * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state. - */ - provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult; - } - - export namespace notebook { - - /** - * All notebook documents currently known to the editor. - */ - export const notebookDocuments: ReadonlyArray; - - /** - * 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. - * - * *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. - * - * *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. - * - * @param uri The resource to open. - * @returns A promise that resolves to a {@link NotebookDocument notebook} - */ - export function openNotebookDocument(uri: Uri): Thenable; - - /** - * An event that is emitted when a {@link NotebookDocument notebook} is opened. - */ - export const onDidOpenNotebookDocument: Event; - - /** - * An event that is emitted when a {@link NotebookDocument notebook} is disposed. - * - * *Note 1:* There is no guarantee that this event fires when an editor tab is closed. - * - * *Note 2:* A notebook can be open but not shown in an editor which means this event can fire - * for a notebook that has not been shown in an editor. - */ - export const onDidCloseNotebookDocument: Event; - - /** - * Register a {@link NotebookSerializer notebook serializer}. - * - * A notebook serializer must to be contributed through the `notebooks` extension point. When opening a notebook file, the editor will send - * the `onNotebook:` activation event, and extensions must register their serializer in return. - * - * @param notebookType A notebook. - * @param serializer A notebook serialzier. - * @param options Optional context options that define what parts of a notebook should be persisted - * @return A {@link Disposable} that unregisters this serializer when being disposed. - */ - export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable; - - /** - * Creates a new notebook controller. - * - * @param id Identifier of the controller. Must be unique per extension. - * @param viewType A notebook view type for which this controller is for. - * @param label The label of the controller - * @param handler - * @param preloads - */ - export function createNotebookController(id: string, viewType: string, label: string, handler?: NotebookExecuteHandler, preloads?: NotebookKernelPreload[]): NotebookController; - - // todo@API what is this used for? - // todo@API qualify cell, ...NotebookCell... - export const onDidChangeNotebookCellExecutionState: Event; - - export function registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditor - - export enum NotebookEditorRevealType { - /** - * The range will be revealed with as little scrolling as possible. - */ - Default = 0, - - /** - * The range will always be revealed in the center of the viewport. - */ - InCenter = 1, - - /** - * If the range is outside the viewport, it will be revealed in the center of the viewport. - * Otherwise, it will be revealed with as little scrolling as possible. - */ - InCenterIfOutsideViewport = 2, - - /** - * The range will always be revealed at the top of the viewport. - */ - AtTop = 3 - } - - export interface NotebookEditor { - /** - * The document associated with this notebook editor. - */ - readonly document: NotebookDocument; - - /** - * The selections on this notebook editor. - * - * The primary selection (or focused range) is `selections[0]`. When the document has no cells, the primary selection is empty `{ start: 0, end: 0 }`; - */ - readonly selections: NotebookRange[]; - - /** - * The current visible ranges in the editor (vertically). - */ - readonly visibleRanges: NotebookRange[]; - - /** - * Scroll as indicated by `revealType` in order to reveal the given range. - * - * @param range A range. - * @param revealType The scrolling strategy for revealing `range`. - */ - revealRange(range: NotebookRange, revealType?: NotebookEditorRevealType): void; - - /** - * The column in which this editor shows. - */ - readonly viewColumn?: ViewColumn; - } - - export interface NotebookDocumentMetadataChangeEvent { - /** - * The {@link NotebookDocument notebook document} for which the document metadata have changed. - */ - readonly document: NotebookDocument; - } - - export interface NotebookCellsChangeData { - readonly start: number; - // todo@API end? Use NotebookCellRange instead? - readonly deletedCount: number; - // todo@API removedCells, deletedCells? - readonly deletedItems: NotebookCell[]; - // todo@API addedCells, insertedCells, newCells? - readonly items: NotebookCell[]; - } - - export interface NotebookCellsChangeEvent { - /** - * The {@link NotebookDocument notebook document} for which the cells have changed. - */ - readonly document: NotebookDocument; - readonly changes: ReadonlyArray; - } - - export interface NotebookCellOutputsChangeEvent { - /** - * The {@link NotebookDocument notebook document} for which the cell outputs have changed. - */ - readonly document: NotebookDocument; - readonly cells: NotebookCell[]; - } - - export interface NotebookCellMetadataChangeEvent { - /** - * The {@link NotebookDocument notebook document} for which the cell metadata have changed. - */ - readonly document: NotebookDocument; - readonly cell: NotebookCell; - } - - export interface NotebookEditorSelectionChangeEvent { - /** - * The {@link NotebookEditor notebook editor} for which the selections have changed. - */ - readonly notebookEditor: NotebookEditor; - readonly selections: ReadonlyArray - } - - export interface NotebookEditorVisibleRangesChangeEvent { - /** - * The {@link NotebookEditor notebook editor} for which the visible ranges have changed. - */ - readonly notebookEditor: NotebookEditor; - readonly visibleRanges: ReadonlyArray; - } - - - export interface NotebookDocumentShowOptions { - viewColumn?: ViewColumn; - preserveFocus?: boolean; - preview?: boolean; - selections?: NotebookRange[]; - } - - export namespace notebook { - - - - export const onDidSaveNotebookDocument: Event; - - export const onDidChangeNotebookDocumentMetadata: Event; - export const onDidChangeNotebookCells: Event; - - // todo@API add onDidChangeNotebookCellOutputs - export const onDidChangeCellOutputs: Event; - - // todo@API add onDidChangeNotebookCellMetadata - export const onDidChangeCellMetadata: Event; - } - - export namespace window { - export const visibleNotebookEditors: NotebookEditor[]; - export const onDidChangeVisibleNotebookEditors: Event; - export const activeNotebookEditor: NotebookEditor | undefined; - export const onDidChangeActiveNotebookEditor: Event; - export const onDidChangeNotebookEditorSelection: Event; - export const onDidChangeNotebookEditorVisibleRanges: Event; - - export function showNotebookDocument(uri: Uri, options?: NotebookDocumentShowOptions): Thenable; - export function showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorEdit - - // todo@API add NotebookEdit-type which handles all these cases? - // export class NotebookEdit { - // range: NotebookRange; - // newCells: NotebookCellData[]; - // newMetadata?: NotebookDocumentMetadata; - // constructor(range: NotebookRange, newCells: NotebookCellData) - // } - - // export class NotebookCellEdit { - // newMetadata?: NotebookCellMetadata; - // } - - // export interface WorkspaceEdit { - // set(uri: Uri, edits: TextEdit[] | NotebookEdit[]): void - // } - - export interface WorkspaceEdit { - // todo@API add NotebookEdit-type which handles all these cases? - replaceNotebookMetadata(uri: Uri, value: NotebookDocumentMetadata): void; - replaceNotebookCells(uri: Uri, range: NotebookRange, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void; - replaceNotebookCellMetadata(uri: Uri, index: number, cellMetadata: NotebookCellMetadata, metadata?: WorkspaceEditEntryMetadata): void; - } - - export interface NotebookEditorEdit { - replaceMetadata(value: NotebookDocumentMetadata): void; - replaceCells(start: number, end: number, cells: NotebookCellData[]): void; - replaceCellMetadata(index: number, metadata: NotebookCellMetadata): void; - } - - export interface NotebookEditor { - /** - * Perform an edit on the notebook associated with this notebook editor. - * - * The given callback-function is invoked with an {@link NotebookEditorEdit edit-builder} which must - * be used to make edits. Note that the edit-builder is only valid while the - * callback executes. - * - * @param callback A function which can create edits using an {@link NotebookEditorEdit edit-builder}. - * @return A promise that resolves with a value indicating if the edits could be applied. - */ - // @jrieken REMOVE maybe - edit(callback: (editBuilder: NotebookEditorEdit) => void): Thenable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorDecorationType - - export interface NotebookEditor { - setDecorations(decorationType: NotebookEditorDecorationType, range: NotebookRange): void; - } - - export interface NotebookDecorationRenderOptions { - backgroundColor?: string | ThemeColor; - borderColor?: string | ThemeColor; - top: ThemableDecorationAttachmentRenderOptions; - } - - export interface NotebookEditorDecorationType { - readonly key: string; - dispose(): void; - } - - export namespace notebook { - export function createNotebookEditorDecorationType(options: NotebookDecorationRenderOptions): NotebookEditorDecorationType; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookConcatTextDocument - - export namespace notebook { - /** - * Create a document that is the concatenation of all notebook cells. By default all code-cells are included - * but a selector can be provided to narrow to down the set of cells. - * - * @param notebook - * @param selector - */ - // todo@API really needed? we didn't find a user here - export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument; - } - - export interface NotebookConcatTextDocument { - readonly uri: Uri; - readonly isClosed: boolean; - dispose(): void; - readonly onDidChange: Event; - readonly version: number; - getText(): string; - getText(range: Range): string; - - offsetAt(position: Position): number; - positionAt(offset: number): Position; - validateRange(range: Range): Range; - validatePosition(position: Position): Position; - - locationAt(positionOrRange: Position | Range): Location; - positionAt(location: Location): Position; - contains(uri: Uri): boolean; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookContentProvider - - - interface NotebookDocumentBackup { - /** - * Unique identifier for the backup. - * - * This id is passed back to your extension in `openNotebook` when opening a notebook editor from a backup. - */ - readonly id: string; - - /** - * Delete the current backup. - * - * This is called by VS Code when it is clear the current backup is no longer needed, such as when a new backup - * is made or when the file is saved. - */ - delete(): void; - } - - interface NotebookDocumentBackupContext { - readonly destination: Uri; - } - - interface NotebookDocumentOpenContext { - readonly backupId?: string; - readonly untitledDocumentData?: Uint8Array; - } - - // todo@API use openNotebookDOCUMENT to align with openCustomDocument etc? - // todo@API rename to NotebookDocumentContentProvider - export interface NotebookContentProvider { - - readonly options?: NotebookDocumentContentOptions; - readonly onDidChangeNotebookContentOptions?: Event; - - /** - * Content providers should always use {@link FileSystemProvider file system providers} to - * resolve the raw content for `uri` as the resouce is not necessarily a file on disk. - */ - openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext, token: CancellationToken): NotebookData | Thenable; - - // todo@API use NotebookData instead - saveNotebook(document: NotebookDocument, token: CancellationToken): Thenable; - - // todo@API use NotebookData instead - saveNotebookAs(targetResource: Uri, document: NotebookDocument, token: CancellationToken): Thenable; - - // todo@API use NotebookData instead - backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, token: CancellationToken): Thenable; - } - - export namespace notebook { - - // TODO@api use NotebookDocumentFilter instead of just notebookType:string? - // TODO@API options duplicates the more powerful variant on NotebookContentProvider - export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions): Disposable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, LiveShare - - export interface NotebookRegistrationData { - displayName: string; - filenamePattern: (GlobPattern | { include: GlobPattern; exclude: GlobPattern; })[]; - exclusive?: boolean; - } - - export namespace notebook { - // SPECIAL overload with NotebookRegistrationData - export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions, registrationData?: NotebookRegistrationData): Disposable; - // SPECIAL overload with NotebookRegistrationData - export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions, registration?: NotebookRegistrationData): Disposable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/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`. - */ - parameters?: string; - - /** - * The fully qualified name, like package name or file path. Rendered after `signature`. - */ - qualifier?: string; - - /** - * The return-type of a function or type of a property/variable. Rendered rightmost. - */ - type?: string; - } - - //#endregion - - //#region @eamodio - timeline: https://github.com/microsoft/vscode/issues/84297 - - export class TimelineItem { - /** - * A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred. - */ - timestamp: number; - - /** - * A human-readable string describing the timeline item. - */ - label: string; - - /** - * Optional id for the timeline item. It must be unique across all the timeline items provided by this source. - * - * If not provided, an id is generated using the timeline item's timestamp. - */ - id?: string; - - /** - * The icon path or {@link ThemeIcon} for the timeline item. - */ - iconPath?: Uri | { light: Uri; dark: Uri; } | ThemeIcon; - - /** - * A human readable string describing less prominent details of the timeline item. - */ - description?: string; - - /** - * The tooltip text when you hover over the timeline item. - */ - detail?: string; - - /** - * The {@link Command} that should be executed when the timeline item is selected. - */ - command?: Command; - - /** - * Context value of the timeline item. This can be used to contribute specific actions to the item. - * For example, a timeline item is given a context value as `commit`. When contributing actions to `timeline/item/context` - * using `menus` extension point, you can specify context value for key `timelineItem` in `when` expression like `timelineItem == commit`. - * ``` - * "contributes": { - * "menus": { - * "timeline/item/context": [ - * { - * "command": "extension.copyCommitId", - * "when": "timelineItem == commit" - * } - * ] - * } - * } - * ``` - * This will show the `extension.copyCommitId` action only for items where `contextValue` is `commit`. - */ - contextValue?: string; - - /** - * Accessibility information used when screen reader interacts with this timeline item. - */ - accessibilityInformation?: AccessibilityInformation; - - /** - * @param label A human-readable string describing the timeline item - * @param timestamp A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred - */ - constructor(label: string, timestamp: number); - } - - export interface TimelineChangeEvent { - /** - * The {@link Uri} of the resource for which the timeline changed. - */ - uri: Uri; - - /** - * A flag which indicates whether the entire timeline should be reset. - */ - reset?: boolean; - } - - export interface Timeline { - readonly paging?: { - /** - * A provider-defined cursor specifying the starting point of timeline items which are after the ones returned. - * Use `undefined` to signal that there are no more items to be returned. - */ - readonly cursor: string | undefined; - }; - - /** - * An array of {@link TimelineItem timeline items}. - */ - readonly items: readonly TimelineItem[]; - } - - export interface TimelineOptions { - /** - * A provider-defined cursor specifying the starting point of the timeline items that should be returned. - */ - cursor?: string; - - /** - * An optional maximum number timeline items or the all timeline items newer (inclusive) than the timestamp or id that should be returned. - * If `undefined` all timeline items should be returned. - */ - limit?: number | { timestamp: number; id?: string; }; - } - - export interface TimelineProvider { - /** - * An optional event to signal that the timeline for a source has changed. - * To signal that the timeline for all resources (uris) has changed, do not pass any argument or pass `undefined`. - */ - onDidChange?: Event; - - /** - * An identifier of the source of the timeline items. This can be used to filter sources. - */ - readonly id: string; - - /** - * A human-readable string describing the source of the timeline items. This can be used as the display label when filtering sources. - */ - readonly label: string; - - /** - * Provide {@link TimelineItem timeline items} for a {@link Uri}. - * - * @param uri The {@link Uri} of the file to provide the timeline for. - * @param options A set of options to determine how results should be returned. - * @param token A cancellation token. - * @return The {@link TimelineResult timeline result} or a thenable that resolves to such. The lack of a result - * can be signaled by returning `undefined`, `null`, or an empty array. - */ - provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult; - } - - export namespace workspace { - /** - * Register a timeline provider. - * - * Multiple providers can be registered. In that case, providers are asked in - * parallel and the results are merged. A failing provider (rejected promise or exception) will - * not cause a failure of the whole operation. - * - * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents. - * @param provider A timeline provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. - */ - export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/91555 - - export enum StandardTokenType { - Other = 0, - Comment = 1, - String = 2, - RegEx = 4 - } - - export interface TokenInformation { - type: StandardTokenType; - range: Range; - } - - export namespace languages { - export function getTokenInformationAtPosition(document: TextDocument, position: Position): Thenable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/16221 - - // todo@API Split between Inlay- and OverlayHints (InlayHint are for a position, OverlayHints for a non-empty range) - // todo@API add "mini-markdown" for links and styles - // (done) remove description - // (done) rename to InlayHint - // (done) add InlayHintKind with type, argument, etc - - export namespace languages { - /** - * Register a inlay hints provider. - * - * Multiple providers can be registered for a language. In that case providers are asked in - * parallel and the results are merged. A failing provider (rejected promise or exception) will - * not cause a failure of the whole operation. - * - * @param selector A selector that defines the documents this provider is applicable to. - * @param provider An inlay hints provider. - * @return A {@link Disposable} that unregisters this provider when being disposed. - */ - export function registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider): Disposable; - } - - export enum InlayHintKind { - Other = 0, - Type = 1, - Parameter = 2, - } - - /** - * Inlay hint information. - */ - export class InlayHint { - /** - * The text of the hint. - */ - text: string; - /** - * The position of this hint. - */ - position: Position; - /** - * The kind of this hint. - */ - kind?: InlayHintKind; - /** - * Whitespace before the hint. - */ - whitespaceBefore?: boolean; - /** - * Whitespace after the hint. - */ - whitespaceAfter?: boolean; - - // todo@API make range first argument - constructor(text: string, position: Position, kind?: InlayHintKind); - } - - /** - * The inlay hints provider interface defines the contract between extensions and - * the inlay hints feature. - */ - export interface InlayHintsProvider { - - /** - * An optional event to signal that inlay hints have changed. - * @see {@link EventEmitter} - */ - onDidChangeInlayHints?: Event; - - /** - * - * @param model The document in which the command was invoked. - * @param range The range for which inlay hints should be computed. - * @param token A cancellation token. - * @return A list of inlay hints or a thenable that resolves to such. - */ - provideInlayHints(model: TextDocument, range: Range, token: CancellationToken): ProviderResult; - } - //#endregion - - //#region https://github.com/microsoft/vscode/issues/104436 - - export enum ExtensionRuntime { - /** - * The extension is running in a NodeJS extension host. Runtime access to NodeJS APIs is available. - */ - Node = 1, - /** - * The extension is running in a Webworker extension host. Runtime access is limited to Webworker APIs. - */ - Webworker = 2 - } - - export interface ExtensionContext { - readonly extensionRuntime: ExtensionRuntime; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/102091 - - export interface TextDocument { - - /** - * The {@link NotebookDocument notebook} that contains this document as a notebook cell or `undefined` when - * the document is not contained by a notebook (this should be the more frequent case). - */ - notebook: NotebookDocument | undefined; - } - //#endregion - - //#region 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; - - /** - * Requests that tests be run by their controller. - * @param run Run options to use - * @param token Cancellation token for the test run - */ - export function runTests(run: TestRunRequest, token?: CancellationToken): Thenable; - - /** - * Returns an observer that 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; - - /** - * 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 VS Code. 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} - */ - 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; - - /** - * List of test results stored by VS Code, sorted in descnding - * 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>; - - /** - * An event that fires when an existing test in the collection changes, or - * null if a top-level test was added or removed. When fired, the consumer - * should check the test item and all its children for changes. - */ - readonly onDidChangeTest: Event; - - /** - * 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 VS Code to eventually tell test - * providers that they no longer need to update tests. - */ - dispose(): void; - } - - /** - * @stability experimental - */ - export interface TestsChangeEvent { - /** - * List of all tests that are newly added. - */ - readonly added: ReadonlyArray>; - - /** - * List of existing tests that have updated. - */ - readonly updated: ReadonlyArray>; - - /** - * List of existing tests that have been removed. - */ - readonly removed: ReadonlyArray>; - } - - /** - * Interface to discover and execute tests. - */ - 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>; - - /** - * 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. - * - * @param options Options for this test run - * @param cancellationToken Token that signals the used asked to abort the test run. - */ - runTests(options: TestRunRequest, token: CancellationToken): Thenable | void; - } - - /** - * Options given to {@link test.runTests}. - */ - export interface TestRunRequest { - /** - * 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}. - */ - tests: TestItem[]; - - /** - * An array of tests the user has marked as excluded in VS Code. May be - * omitted if no exclusions were requested. Test controllers should not run - * excluded tests or any children of excluded tests. - */ - exclude?: TestItem[]; - - /** - * Whether tests in this run should be debugged. - */ - debug: boolean; - } - - /** - * 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; - - /** - * 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 VS Code 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 { - /** - * Unique identifier that matches that of the associated TestItem. - * This is used to correlate test results and tests in the document with - * those in the workspace (test explorer). - */ - readonly id: string; - - /** - * URI this TestItem is associated with. May be a file or file. - */ - readonly uri?: Uri; - - /** - * Display name describing the test case. - */ - readonly label: string; - - /** - * Optional description that appears next to the label. - */ - readonly description?: string; - - /** - * Location of the test item in its `uri`. This is only meaningful if the - * `uri` points to a file. - */ - readonly range?: Range; - - /** - * State of the test in each task. In the common case, a test will only - * be executed in a single task and the length of this array will be 1. - */ - readonly taskStates: ReadonlyArray; - - /** - * Optional list of nested tests for this item. - */ - readonly children: Readonly[]; - } - - export interface TestSnapshoptTaskState { - /** - * Current result of the test. - */ - readonly state: TestResultState; - - /** - * The number of milliseconds the test took to run. This is set once the - * `state` is `Passed`, `Failed`, or `Errored`. - */ - readonly duration?: number; - - /** - * Associated test run message. Can, for example, contain assertion - * failure information if the test fails. - */ - readonly messages: ReadonlyArray; - } - - //#endregion - - //#region Opener service (https://github.com/microsoft/vscode/issues/109277) - - /** - * Details if an `ExternalUriOpener` can open a uri. - * - * The priority is also used to rank multiple openers against each other and determine - * if an opener should be selected automatically or if the user should be prompted to - * select an opener. - * - * VS Code will try to use the best available opener, as sorted by `ExternalUriOpenerPriority`. - * If there are multiple potential "best" openers for a URI, then the user will be prompted - * to select an opener. - */ - export enum ExternalUriOpenerPriority { - /** - * The opener is disabled and will never be shown to users. - * - * Note that the opener can still be used if the user specifically - * configures it in their settings. - */ - None = 0, - - /** - * The opener can open the uri but will not cause a prompt on its own - * since VS Code always contributes a built-in `Default` opener. - */ - Option = 1, - - /** - * The opener can open the uri. - * - * VS Code's built-in opener has `Default` priority. This means that any additional `Default` - * openers will cause the user to be prompted to select from a list of all potential openers. - */ - Default = 2, - - /** - * The opener can open the uri and should be automatically selected over any - * default openers, include the built-in one from VS Code. - * - * A preferred opener will be automatically selected if no other preferred openers - * are available. If multiple preferred openers are available, then the user - * is shown a prompt with all potential openers (not just preferred openers). - */ - Preferred = 3, - } - - /** - * Handles opening uris to external resources, such as http(s) links. - * - * Extensions can implement an `ExternalUriOpener` to open `http` links to a webserver - * inside of VS Code instead of having the link be opened by the web browser. - * - * Currently openers may only be registered for `http` and `https` uris. - */ - export interface ExternalUriOpener { - - /** - * Check if the opener can open a uri. - * - * @param uri The uri being opened. This is the uri that the user clicked on. It has - * not yet gone through port forwarding. - * @param token Cancellation token indicating that the result is no longer needed. - * - * @return Priority indicating if the opener can open the external uri. - */ - canOpenExternalUri(uri: Uri, token: CancellationToken): ExternalUriOpenerPriority | Thenable; - - /** - * Open a uri. - * - * This is invoked when: - * - * - The user clicks a link which does not have an assigned opener. In this case, first `canOpenExternalUri` - * is called and if the user selects this opener, then `openExternalUri` is called. - * - The user sets the default opener for a link in their settings and then visits a link. - * - * @param resolvedUri The uri to open. This uri may have been transformed by port forwarding, so it - * may not match the original uri passed to `canOpenExternalUri`. Use `ctx.originalUri` to check the - * original uri. - * @param ctx Additional information about the uri being opened. - * @param token Cancellation token indicating that opening has been canceled. - * - * @return Thenable indicating that the opening has completed. - */ - openExternalUri(resolvedUri: Uri, ctx: OpenExternalUriContext, token: CancellationToken): Thenable | void; - } - - /** - * Additional information about the uri being opened. - */ - interface OpenExternalUriContext { - /** - * The uri that triggered the open. - * - * This is the original uri that the user clicked on or that was passed to `openExternal.` - * Due to port forwarding, this may not match the `resolvedUri` passed to `openExternalUri`. - */ - readonly sourceUri: Uri; - } - - /** - * Additional metadata about a registered `ExternalUriOpener`. - */ - interface ExternalUriOpenerMetadata { - - /** - * List of uri schemes the opener is triggered for. - * - * Currently only `http` and `https` are supported. - */ - readonly schemes: readonly string[] - - /** - * Text displayed to the user that explains what the opener does. - * - * For example, 'Open in browser preview' - */ - readonly label: string; - } - - namespace window { - /** - * Register a new `ExternalUriOpener`. - * - * When a uri is about to be opened, an `onOpenExternalUri:SCHEME` activation event is fired. - * - * @param id Unique id of the opener, such as `myExtension.browserPreview`. This is used in settings - * and commands to identify the opener. - * @param opener Opener to register. - * @param metadata Additional information about the opener. - * - * @returns Disposable that unregisters the opener. - */ - export function registerExternalUriOpener(id: string, opener: ExternalUriOpener, metadata: ExternalUriOpenerMetadata): Disposable; - } - - interface OpenExternalOptions { - /** - * Allows using openers contributed by extensions through `registerExternalUriOpener` - * when opening the resource. - * - * If `true`, VS Code will check if any contributed openers can handle the - * uri, and fallback to the default opener behavior. - * - * If it is string, this specifies the id of the `ExternalUriOpener` - * that should be used if it is available. Use `'default'` to force VS Code's - * standard external opener to be used. - */ - readonly allowContributedOpeners?: boolean | string; - } - - namespace env { - export function openExternal(target: Uri, options?: OpenExternalOptions): Thenable; - } - - //#endregion - - //#region https://github.com/Microsoft/vscode/issues/15178 - - // TODO@API must be a class - export interface OpenEditorInfo { - name: string; - resource: Uri; - isActive: boolean; - } - - export namespace window { - export const openEditors: ReadonlyArray; - - // todo@API proper event type - export const onDidChangeOpenEditors: Event; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/120173 - /** - * The object describing the properties of the workspace trust request - */ - export interface WorkspaceTrustRequestOptions { - /** - * Custom message describing the user action that requires workspace - * trust. If omitted, a generic message will be displayed in the workspace - * trust request dialog. - */ - readonly message?: string; - } - - export namespace workspace { - /** - * Prompt the user to chose whether to trust the current workspace - * @param options Optional object describing the properties of the - * workspace trust request. - */ - export function requestWorkspaceTrust(options?: WorkspaceTrustRequestOptions): Thenable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/115616 @alexr00 - export enum PortAutoForwardAction { - Notify = 1, - OpenBrowser = 2, - OpenPreview = 3, - Silent = 4, - Ignore = 5 - } - - export class PortAttributes { - /** - * The port number associated with this this set of attributes. - */ - port: number; - - /** - * The action to be taken when this port is detected for auto forwarding. - */ - autoForwardAction: PortAutoForwardAction; - - /** - * Creates a new PortAttributes object - * @param port the port number - * @param autoForwardAction the action to take when this port is detected - */ - constructor(port: number, autoForwardAction: PortAutoForwardAction); - } - - export interface PortAttributesProvider { - /** - * Provides attributes for the given port. For ports that your extension doesn't know about, simply - * return undefined. For example, if `providePortAttributes` is called with ports 3000 but your - * extension doesn't know anything about 3000 you should return undefined. - */ - providePortAttributes(port: number, pid: number | undefined, commandLine: string | undefined, token: CancellationToken): ProviderResult; - } - - export namespace workspace { - /** - * If your extension listens on ports, consider registering a PortAttributesProvider to provide information - * about the ports. For example, a debug extension may know about debug ports in it's debuggee. By providing - * this information with a PortAttributesProvider the extension can tell VS Code that these ports should be - * ignored, since they don't need to be user facing. - * - * @param portSelector If registerPortAttributesProvider is called after you start your process then you may already - * know the range of ports or the pid of your process. All properties of a the portSelector must be true for your - * provider to get called. - * The `portRange` is start inclusive and end exclusive. - * @param provider The PortAttributesProvider - */ - export function registerPortAttributesProvider(portSelector: { pid?: number, portRange?: [number, number], commandMatcher?: RegExp }, provider: PortAttributesProvider): Disposable; - } - //#endregion - - //#region https://github.com/microsoft/vscode/issues/119904 @eamodio - - export interface SourceControlInputBox { - - /** - * Sets focus to the input. - */ - focus(): void; - } - - //#endregion + //#region 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 + + export interface MessageOptions { + /** + * Do not render a native message box. + */ + useCustom?: boolean; + } + + export interface RemoteAuthorityResolverContext { + resolveAttempt: number; + } + + export class ResolvedAuthority { + readonly host: string; + readonly port: number; + readonly connectionToken: string | undefined; + + constructor(host: string, port: number, connectionToken?: string); + } + + export enum RemoteTrustOption { + Unknown = 0, + DisableTrust = 1, + MachineTrusted = 2 + } + + export interface ResolvedOptions { + extensionHostEnv?: { [key: string]: string | null; }; + + trust?: RemoteTrustOption; + } + + export interface TunnelOptions { + remoteAddress: { port: number, host: string; }; + // The desired local port. If this port can't be used, then another will be chosen. + localAddressPort?: number; + label?: string; + public?: boolean; + } + + export interface TunnelDescription { + remoteAddress: { port: number, host: string; }; + //The complete local address(ex. localhost:1234) + localAddress: { port: number, host: string; } | string; + public?: boolean; + } + + export interface Tunnel extends TunnelDescription { + // Implementers of Tunnel should fire onDidDispose when dispose is called. + onDidDispose: Event; + dispose(): void | Thenable; + } + + /** + * Used as part of the ResolverResult if the extension has any candidate, + * published, or forwarded ports. + */ + export interface TunnelInformation { + /** + * Tunnels that are detected by the extension. The remotePort is used for display purposes. + * The localAddress should be the complete local address (ex. localhost:1234) for connecting to the port. Tunnels provided through + * detected are read-only from the forwarded ports UI. + */ + environmentTunnels?: TunnelDescription[]; + + } + + export interface TunnelCreationOptions { + /** + * True when the local operating system will require elevation to use the requested local port. + */ + elevationRequired?: boolean; + } + + export enum CandidatePortSource { + None = 0, + Process = 1, + Output = 2 + } + + export type ResolverResult = ResolvedAuthority & ResolvedOptions & TunnelInformation; + + export class RemoteAuthorityResolverError extends Error { + static NotAvailable(message?: string, handled?: boolean): RemoteAuthorityResolverError; + static TemporarilyNotAvailable(message?: string): RemoteAuthorityResolverError; + + constructor(message?: string); + } + + export interface RemoteAuthorityResolver { + resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable; + /** + * Can be optionally implemented if the extension can forward ports better than the core. + * When not implemented, the core will use its default forwarding logic. + * When implemented, the core will use this to forward ports. + * + * To enable the "Change Local Port" action on forwarded ports, make sure to set the `localAddress` of + * the returned `Tunnel` to a `{ port: number, host: string; }` and not a string. + */ + tunnelFactory?: (tunnelOptions: TunnelOptions, tunnelCreationOptions: TunnelCreationOptions) => Thenable | undefined; + + /**p + * Provides filtering for candidate ports. + */ + showCandidatePort?: (host: string, port: number, detail: string) => Thenable; + + /** + * Lets the resolver declare which tunnel factory features it supports. + * UNDER DISCUSSION! MAY CHANGE SOON. + */ + tunnelFeatures?: { + elevation: boolean; + public: boolean; + }; + + candidatePortSource?: CandidatePortSource; + } + + export namespace workspace { + /** + * Forwards a port. If the current resolver implements RemoteAuthorityResolver:forwardPort then that will be used to make the tunnel. + * By default, openTunnel only support localhost; however, RemoteAuthorityResolver:tunnelFactory can be used to support other ips. + * + * @throws When run in an environment without a remote. + * + * @param tunnelOptions The `localPort` is a suggestion only. If that port is not available another will be chosen. + */ + export function openTunnel(tunnelOptions: TunnelOptions): Thenable; + + /** + * Gets an array of the currently available tunnels. This does not include environment tunnels, only tunnels that have been created by the user. + * Note that these are of type TunnelDescription and cannot be disposed. + */ + export let tunnels: Thenable; + + /** + * Fired when the list of tunnels has changed. + */ + export const onDidChangeTunnels: Event; + } + + export interface ResourceLabelFormatter { + scheme: string; + authority?: string; + formatting: ResourceLabelFormatting; + } + + export interface ResourceLabelFormatting { + label: string; // myLabel:/${path} + // For historic reasons we use an or string here. Once we finalize this API we should start using enums instead and adopt it in extensions. + // eslint-disable-next-line vscode-dts-literal-or-types + separator: '/' | '\\' | ''; + tildify?: boolean; + normalizeDriveLetter?: boolean; + workspaceSuffix?: string; + authorityPrefix?: string; + stripPathStartingSeparator?: boolean; + } + + export namespace workspace { + export function registerRemoteAuthorityResolver(authorityPrefix: string, resolver: RemoteAuthorityResolver): Disposable; + export function registerResourceLabelFormatter(formatter: ResourceLabelFormatter): Disposable; + } + + //#endregion + + //#region editor insets: https://github.com/microsoft/vscode/issues/85682 + + export interface WebviewEditorInset { + readonly editor: TextEditor; + readonly line: number; + readonly height: number; + readonly webview: Webview; + readonly onDidDispose: Event; + dispose(): void; + } + + export namespace window { + export function createWebviewTextEditorInset(editor: TextEditor, line: number, height: number, options?: WebviewOptions): WebviewEditorInset; + } + + //#endregion + + //#region read/write in chunks: https://github.com/microsoft/vscode/issues/84515 + + export interface FileSystemProvider { + open?(resource: Uri, options: { create: boolean; }): number | Thenable; + close?(fd: number): void | Thenable; + read?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable; + write?(fd: number, pos: number, data: Uint8Array, offset: number, length: number): number | Thenable; + } + + //#endregion + + //#region TextSearchProvider: https://github.com/microsoft/vscode/issues/59921 + + /** + * The parameters of a query for text search. + */ + export interface TextSearchQuery { + /** + * The text pattern to search for. + */ + pattern: string; + + /** + * Whether or not `pattern` should match multiple lines of text. + */ + isMultiline?: boolean; + + /** + * Whether or not `pattern` should be interpreted as a regular expression. + */ + isRegExp?: boolean; + + /** + * Whether or not the search should be case-sensitive. + */ + isCaseSensitive?: boolean; + + /** + * Whether or not to search for whole word matches only. + */ + isWordMatch?: boolean; + } + + /** + * A file glob pattern to match file paths against. + * TODO@roblourens merge this with the GlobPattern docs/definition in vscode.d.ts. + * @see {@link GlobPattern} + */ + export type GlobString = string; + + /** + * Options common to file and text search + */ + export interface SearchOptions { + /** + * The root folder to search within. + */ + folder: Uri; + + /** + * Files that match an `includes` glob pattern should be included in the search. + */ + includes: GlobString[]; + + /** + * Files that match an `excludes` glob pattern should be excluded from the search. + */ + excludes: GlobString[]; + + /** + * Whether external files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useIgnoreFiles"`. + */ + useIgnoreFiles: boolean; + + /** + * Whether symlinks should be followed while searching. + * See the vscode setting `"search.followSymlinks"`. + */ + followSymlinks: boolean; + + /** + * Whether global files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useGlobalIgnoreFiles"`. + */ + useGlobalIgnoreFiles: boolean; + } + + /** + * Options to specify the size of the result text preview. + * These options don't affect the size of the match itself, just the amount of preview text. + */ + export interface TextSearchPreviewOptions { + /** + * The maximum number of lines in the preview. + * Only search providers that support multiline search will ever return more than one line in the match. + */ + matchLines: number; + + /** + * The maximum number of characters included per line. + */ + charsPerLine: number; + } + + /** + * Options that apply to text search. + */ + export interface TextSearchOptions extends SearchOptions { + /** + * The maximum number of results to be returned. + */ + maxResults: number; + + /** + * Options to specify the size of the result text preview. + */ + previewOptions?: TextSearchPreviewOptions; + + /** + * Exclude files larger than `maxFileSize` in bytes. + */ + maxFileSize?: number; + + /** + * Interpret files using this encoding. + * See the vscode setting `"files.encoding"` + */ + encoding?: string; + + /** + * Number of lines of context to include before each match. + */ + beforeContext?: number; + + /** + * Number of lines of context to include after each match. + */ + afterContext?: number; + } + + /** + * Represents the severiry of a TextSearchComplete message. + */ + export enum TextSearchCompleteMessageType { + Information = 1, + Warning = 2, + } + + /** + * A message regarding a completed search. + */ + export interface TextSearchCompleteMessage { + /** + * Markdown text of the message. + */ + text: string, + /** + * Whether the source of the message is trusted, command links are disabled for untrusted message sources. + * Messaged are untrusted by default. + */ + trusted?: boolean, + /** + * The message type, this affects how the message will be rendered. + */ + type: TextSearchCompleteMessageType, + } + + /** + * Information collected when text search is complete. + */ + export interface TextSearchComplete { + /** + * Whether the search hit the limit on the maximum number of search results. + * `maxResults` on {@link TextSearchOptions `TextSearchOptions`} specifies the max number of results. + * - If exactly that number of matches exist, this should be false. + * - If `maxResults` matches are returned and more exist, this should be true. + * - If search hits an internal limit which is less than `maxResults`, this should be true. + */ + limitHit?: boolean; + + /** + * Additional information regarding the state of the completed search. + * + * Messages with "Information" tyle support links in markdown syntax: + * - Click to [run a command](command:workbench.action.OpenQuickPick) + * - Click to [open a website](https://aka.ms) + * + * Commands may optionally return { triggerSearch: true } to signal to VS Code that the original search should run be agian. + */ + message?: TextSearchCompleteMessage | TextSearchCompleteMessage[]; + } + + /** + * A preview of the text result. + */ + export interface TextSearchMatchPreview { + /** + * The matching lines of text, or a portion of the matching line that contains the match. + */ + text: string; + + /** + * The Range within `text` corresponding to the text of the match. + * The number of matches must match the TextSearchMatch's range property. + */ + matches: Range | Range[]; + } + + /** + * A match from a text search + */ + export interface TextSearchMatch { + /** + * The uri for the matching document. + */ + uri: Uri; + + /** + * The range of the match within the document, or multiple ranges for multiple matches. + */ + ranges: Range | Range[]; + + /** + * A preview of the text match. + */ + preview: TextSearchMatchPreview; + } + + /** + * A line of context surrounding a TextSearchMatch. + */ + export interface TextSearchContext { + /** + * The uri for the matching document. + */ + uri: Uri; + + /** + * One line of text. + * previewOptions.charsPerLine applies to this + */ + text: string; + + /** + * The line number of this line of context. + */ + lineNumber: number; + } + + export type TextSearchResult = TextSearchMatch | TextSearchContext; + + /** + * A TextSearchProvider provides search results for text results inside files in the workspace. + */ + export interface TextSearchProvider { + /** + * Provide results that match the given text pattern. + * @param query The parameters for this query. + * @param options A set of options to consider while searching. + * @param progress A progress callback that must be invoked for all results. + * @param token A cancellation token. + */ + provideTextSearchResults(query: TextSearchQuery, options: TextSearchOptions, progress: Progress, token: CancellationToken): ProviderResult; + } + + //#endregion + + //#region FileSearchProvider: https://github.com/microsoft/vscode/issues/73524 + + /** + * The parameters of a query for file search. + */ + export interface FileSearchQuery { + /** + * The search pattern to match against file paths. + */ + pattern: string; + } + + /** + * Options that apply to file search. + */ + export interface FileSearchOptions extends SearchOptions { + /** + * The maximum number of results to be returned. + */ + maxResults?: number; + + /** + * A CancellationToken that represents the session for this search query. If the provider chooses to, this object can be used as the key for a cache, + * and searches with the same session object can search the same cache. When the token is cancelled, the session is complete and the cache can be cleared. + */ + session?: CancellationToken; + } + + /** + * A FileSearchProvider provides search results for files in the given folder that match a query string. It can be invoked by quickopen or other extensions. + * + * A FileSearchProvider is the more powerful of two ways to implement file search in VS Code. Use a FileSearchProvider if you wish to search within a folder for + * all files that match the user's query. + * + * The FileSearchProvider will be invoked on every keypress in quickopen. When `workspace.findFiles` is called, it will be invoked with an empty query string, + * and in that case, every file in the folder should be returned. + */ + export interface FileSearchProvider { + /** + * Provide the set of files that match a certain file path pattern. + * @param query The parameters for this query. + * @param options A set of options to consider while searching files. + * @param token A cancellation token. + */ + provideFileSearchResults(query: FileSearchQuery, options: FileSearchOptions, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * Register a search provider. + * + * Only one provider can be registered per scheme. + * + * @param scheme The provider will be invoked for workspace folders that have this file scheme. + * @param provider The provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable; + + /** + * Register a text search provider. + * + * Only one provider can be registered per scheme. + * + * @param scheme The provider will be invoked for workspace folders that have this file scheme. + * @param provider The provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable; + } + + //#endregion + + //#region findTextInFiles: https://github.com/microsoft/vscode/issues/59924 + + /** + * Options that can be set on a findTextInFiles search. + */ + export interface FindTextInFilesOptions { + /** + * A {@link GlobPattern glob pattern} that defines the files to search for. The glob pattern + * will be matched against the file paths of files relative to their workspace. Use a {@link RelativePattern relative pattern} + * to restrict the search results to a {@link WorkspaceFolder workspace folder}. + */ + include?: GlobPattern; + + /** + * A {@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern + * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes will + * apply. + */ + exclude?: GlobPattern; + + /** + * Whether to use the default and user-configured excludes. Defaults to true. + */ + useDefaultExcludes?: boolean; + + /** + * The maximum number of results to search for + */ + maxResults?: number; + + /** + * Whether external files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useIgnoreFiles"`. + */ + useIgnoreFiles?: boolean; + + /** + * Whether global files that exclude files, like .gitignore, should be respected. + * See the vscode setting `"search.useGlobalIgnoreFiles"`. + */ + useGlobalIgnoreFiles?: boolean; + + /** + * Whether symlinks should be followed while searching. + * See the vscode setting `"search.followSymlinks"`. + */ + followSymlinks?: boolean; + + /** + * Interpret files using this encoding. + * See the vscode setting `"files.encoding"` + */ + encoding?: string; + + /** + * Options to specify the size of the result text preview. + */ + previewOptions?: TextSearchPreviewOptions; + + /** + * Number of lines of context to include before each match. + */ + beforeContext?: number; + + /** + * Number of lines of context to include after each match. + */ + afterContext?: number; + } + + export namespace workspace { + /** + * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. + * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. + * @param callback A callback, called for each result + * @param token A token that can be used to signal cancellation to the underlying search engine. + * @return A thenable that resolves when the search is complete. + */ + export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; + + /** + * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. + * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. + * @param options An optional set of query options. Include and exclude patterns, maxResults, etc. + * @param callback A callback, called for each result + * @param token A token that can be used to signal cancellation to the underlying search engine. + * @return A thenable that resolves when the search is complete. + */ + export function findTextInFiles(query: TextSearchQuery, options: FindTextInFilesOptions, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; + } + + //#endregion + + //#region diff command: https://github.com/microsoft/vscode/issues/84899 + + /** + * The contiguous set of modified lines in a diff. + */ + export interface LineChange { + readonly originalStartLineNumber: number; + readonly originalEndLineNumber: number; + readonly modifiedStartLineNumber: number; + readonly modifiedEndLineNumber: number; + } + + export namespace commands { + + /** + * Registers a diff information command that can be invoked via a keyboard shortcut, + * a menu item, an action, or directly. + * + * Diff information commands are different from ordinary {@link commands.registerCommand commands} as + * they only execute when there is an active diff editor when the command is called, and the diff + * information has been computed. Also, the command handler of an editor command has access to + * the diff information. + * + * @param command A unique identifier for the command. + * @param callback A command handler function with access to the {@link LineChange diff information}. + * @param thisArg The `this` context used when invoking the handler function. + * @return Disposable which unregisters this command on disposal. + */ + export function registerDiffInformationCommand(command: string, callback: (diff: LineChange[], ...args: any[]) => any, thisArg?: any): Disposable; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @weinand: variables view action contributions + + /** + * A DebugProtocolVariableContainer is an opaque stand-in type for the intersection of the Scope and Variable types defined in the Debug Adapter Protocol. + * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Scope and https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. + */ + export interface DebugProtocolVariableContainer { + // Properties: the intersection of DAP's Scope and Variable types. + } + + /** + * A DebugProtocolVariable is an opaque stand-in type for the Variable type defined in the Debug Adapter Protocol. + * See https://microsoft.github.io/debug-adapter-protocol/specification#Types_Variable. + */ + export interface DebugProtocolVariable { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Variable). + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @joaomoreno: SCM validation + + /** + * Represents the validation type of the Source Control input. + */ + export enum SourceControlInputBoxValidationType { + + /** + * Something not allowed by the rules of a language or other means. + */ + Error = 0, + + /** + * Something suspicious but allowed. + */ + Warning = 1, + + /** + * Something to inform about but not a problem. + */ + Information = 2 + } + + export interface SourceControlInputBoxValidation { + + /** + * The validation message to display. + */ + readonly message: string; + + /** + * The validation type. + */ + readonly type: SourceControlInputBoxValidationType; + } + + /** + * Represents the input box in the Source Control viewlet. + */ + export interface SourceControlInputBox { + + /** + * Shows a transient contextual message on the input. + */ + showValidationMessage(message: string, type: SourceControlInputBoxValidationType): void; + + /** + * A validation function for the input box. It's possible to change + * the validation provider simply by setting this property to a different function. + */ + validateInput?(value: string, cursorPosition: number): ProviderResult; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @joaomoreno: SCM selected provider + + export interface SourceControl { + + /** + * Whether the source control is selected. + */ + readonly selected: boolean; + + /** + * An event signaling when the selection state changes. + */ + readonly onDidChangeSelection: Event; + } + + //#endregion + + //#region Terminal data write event https://github.com/microsoft/vscode/issues/78502 + + export interface TerminalDataWriteEvent { + /** + * The {@link Terminal} for which the data was written. + */ + readonly terminal: Terminal; + /** + * The data being written. + */ + readonly data: string; + } + + namespace window { + /** + * An event which fires when the terminal's child pseudo-device is written to (the shell). + * In other words, this provides access to the raw data stream from the process running + * within the terminal, including VT sequences. + */ + export const onDidWriteTerminalData: Event; + } + + //#endregion + + //#region Terminal dimensions property and change event https://github.com/microsoft/vscode/issues/55718 + + /** + * An {@link Event} which fires when a {@link Terminal}'s dimensions change. + */ + export interface TerminalDimensionsChangeEvent { + /** + * The {@link Terminal} for which the dimensions have changed. + */ + readonly terminal: Terminal; + /** + * The new value for the {@link Terminal.dimensions terminal's dimensions}. + */ + readonly dimensions: TerminalDimensions; + } + + export namespace window { + /** + * An event which fires when the {@link Terminal.dimensions dimensions} of the terminal change. + */ + export const onDidChangeTerminalDimensions: Event; + } + + export interface Terminal { + /** + * The current dimensions of the terminal. This will be `undefined` immediately after the + * terminal is created as the dimensions are not known until shortly after the terminal is + * created. + */ + readonly dimensions: TerminalDimensions | undefined; + } + + //#endregion + + //#region Terminal name change event https://github.com/microsoft/vscode/issues/114898 + + export interface Pseudoterminal { + /** + * An event that when fired allows changing the name of the terminal. + * + * **Example:** Change the terminal name to "My new terminal". + * ```typescript + * const writeEmitter = new vscode.EventEmitter(); + * const changeNameEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * onDidChangeName: changeNameEmitter.event, + * open: () => changeNameEmitter.fire('My new terminal'), + * close: () => {} + * }; + * vscode.window.createTerminal({ name: 'My terminal', pty }); + * ``` + */ + onDidChangeName?: Event; + } + + //#endregion + + //#region Terminal icon https://github.com/microsoft/vscode/issues/120538 + + export interface TerminalOptions { + /** + * A codicon ID to associate with this terminal. + */ + readonly icon?: string; + } + + //#endregion + + // eslint-disable-next-line vscode-dts-region-comments + //#region @jrieken -> exclusive document filters + + export interface DocumentFilter { + readonly exclusive?: boolean; + } + + //#endregion + + //#region Tree View: https://github.com/microsoft/vscode/issues/61313 @alexr00 + export interface TreeView extends Disposable { + reveal(element: T | undefined, options?: { select?: boolean, focus?: boolean, expand?: boolean | number; }): Thenable; + } + //#endregion + + //#region Custom Tree View Drag and Drop https://github.com/microsoft/vscode/issues/32592 + export interface TreeViewOptions { + dragAndDropController?: DragAndDropController; + } + + export interface DragAndDropController extends Disposable { + /** + * Extensions should fire `TreeDataProvider.onDidChangeTreeData` for any elements that need to be refreshed. + * + * @param source + * @param target + */ + onDrop(source: T[], target: T): Thenable; + } + //#endregion + + //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 + export interface TaskPresentationOptions { + /** + * Controls whether the task is executed in a specific terminal group using split panes. + */ + group?: string; + } + //#endregion + + //#region Status bar item with ID and Name: https://github.com/microsoft/vscode/issues/74972 + + /** + * Options to configure the status bar item. + */ + export interface StatusBarItemOptions { + + /** + * An identifier for the item that should be unique. + */ + id: string; + + /** + * A human readable name of the item that explains the purpose + * of the item to the user. + */ + name: string; + + /** + * The alignment of the item. + */ + alignment?: StatusBarAlignment; + + /** + * The priority of the item. Higher values mean the item should be shown more to the left. + */ + priority?: number; + } + + export namespace window { + + /** + * Creates a status bar {@link StatusBarItem item}. + * + * @param options The options of the item. If not provided, some default values + * will be assumed. For example, the {@link StatusBarItemOptions.id `StatusBarItemOptions.id`} + * will be the id of the extension and the {@link StatusBarItemOptions.name `StatusBarItemOptions.name`} + * will be the extension name. + * @return A new status bar item. + */ + export function createStatusBarItem(options?: StatusBarItemOptions): StatusBarItem; + } + + //#endregion + + //#region Custom editor move https://github.com/microsoft/vscode/issues/86146 + + // TODO: Also for custom editor + + export interface CustomTextEditorProvider { + + /** + * Handle when the underlying resource for a custom editor is renamed. + * + * This allows the webview for the editor be preserved throughout the rename. If this method is not implemented, + * VS Code will destory the previous custom editor and create a replacement one. + * + * @param newDocument New text document to use for the custom editor. + * @param existingWebviewPanel Webview panel for the custom editor. + * @param token A cancellation token that indicates the result is no longer needed. + * + * @return Thenable indicating that the webview editor has been moved. + */ + // eslint-disable-next-line vscode-dts-provider-naming + moveCustomTextEditor?(newDocument: TextDocument, existingWebviewPanel: WebviewPanel, token: CancellationToken): Thenable; + } + + //#endregion + + //#region allow QuickPicks to skip sorting: https://github.com/microsoft/vscode/issues/73904 + + export interface QuickPick extends QuickInput { + /** + * An optional flag to sort the final results by index of first query match in label. Defaults to true. + */ + sortByLabel: boolean; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/122922, Notebook, Finalization 1 + + /** + * A notebook cell kind. + */ + export enum NotebookCellKind { + + /** + * A markup-cell is formatted source that is used for display. + */ + Markup = 1, + + /** + * A code-cell is source that can be {@link NotebookController executed} and that + * produces {@link NotebookCellOutput output}. + */ + Code = 2 + } + + /** + * Represents a cell of a {@link NotebookDocument notebook}, either a {@link NotebookCellKind.Code code}-cell + * or {@link NotebookCellKind.Markup markup}-cell. + * + * NotebookCell instances are immutable and are kept in sync for as long as they are part of their notebook. + */ + export interface NotebookCell { + + /** + * The index of this cell in its {@link NotebookDocument.cellAt containing notebook}. The + * index is updated when a cell is moved within its notebook. The index is `-1` + * when the cell has been removed from its notebook. + */ + readonly index: number; + + /** + * The {@link NotebookDocument notebook} that contains this cell. + */ + readonly notebook: NotebookDocument; + + /** + * The kind of this cell. + */ + readonly kind: NotebookCellKind; + + /** + * The {@link TextDocument text} of this cell, represented as text document. + */ + readonly document: TextDocument; + + /** + * The metadata of this cell. + */ + readonly metadata: NotebookCellMetadata + + /** + * The outputs of this cell. + */ + readonly outputs: ReadonlyArray; + + /** + * The most recent {@link NotebookCellExecutionSummary excution summary} for this cell. + */ + readonly executionSummary?: NotebookCellExecutionSummary; + } + + /** + * Represents a notebook which itself is a sequence of {@link NotebookCell code or markup cells}. Notebook documents are + * created from {@link NotebookData notebook data}. + */ + export interface NotebookDocument { + + /** + * The associated uri for this notebook. + * + * *Note* that most notebooks use the `file`-scheme, which means they are files on disk. However, **not** all notebooks are + * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk. + * + * @see {@link FileSystemProvider} + * @see {@link TextDocumentContentProvider} + */ + readonly uri: Uri; + + // todo@API should we really expose this? + // todo@API should this be called `notebookType` or `notebookKind` + readonly viewType: string; + + /** + * The version number of this notebook (it will strictly increase after each + * change, including undo/redo). + */ + readonly version: number; + + /** + * `true` if there are unpersisted changes. + */ + readonly isDirty: boolean; + + /** + * Is this notebook representing an untitled file which has not been saved yet. + */ + readonly isUntitled: boolean; + + /** + * `true` if the notebook has been closed. A closed notebook isn't synchronized anymore + * and won't be re-used when the same resource is opened again. + */ + readonly isClosed: boolean; + + /** + * The {@link NotebookDocumentMetadata metadata} for this notebook. + */ + readonly metadata: NotebookDocumentMetadata; + + /** + * The number of cells in the notebook. + */ + readonly cellCount: number; + + /** + * Return the cell at the specified index. The index will be adjusted to the notebook. + * + * @param index - The index of the cell to retrieve. + * @return A {@link NotebookCell cell}. + */ + cellAt(index: number): NotebookCell; + + /** + * Get the cells of this notebook. A subset can be retrieved by providing + * a range. The range will be adjuset to the notebook. + * + * @param range A notebook range. + * @returns The cells contained by the range or all cells. + */ + getCells(range?: NotebookRange): NotebookCell[]; + + /** + * Save the document. The saving will be handled by the corresponding content provider + * + * @return A promise that will resolve to true when the document + * has been saved. If the file was not dirty or the save failed, + * will return false. + */ + save(): Thenable; + } + + export class NotebookCellMetadata { + /** + * Whether a code cell's editor is collapsed + */ + readonly inputCollapsed?: boolean; + + /** + * Whether a code cell's outputs are collapsed + */ + readonly outputCollapsed?: boolean; + + /** + * Additional attributes of a cell metadata. + */ + readonly [key: string]: any; + + /** + * Create a new notebook cell metadata. + * + * @param inputCollapsed Whether a code cell's editor is collapsed + * @param outputCollapsed Whether a code cell's outputs are collapsed + */ + constructor(inputCollapsed?: boolean, outputCollapsed?: boolean); + + /** + * Derived a new cell metadata from this metadata. + * + * @param change An object that describes a change to this NotebookCellMetadata. + * @return A new NotebookCellMetadata that reflects the given change. Will return `this` NotebookCellMetadata if the change + * is not changing anything. + */ + with(change: { inputCollapsed?: boolean | null, outputCollapsed?: boolean | null, [key: string]: any }): NotebookCellMetadata; + } + + export interface NotebookCellExecutionSummary { + readonly executionOrder?: number; + readonly success?: boolean; + readonly startTime?: number; + readonly endTime?: number; + } + + export class NotebookDocumentMetadata { + /** + * Additional attributes of the document metadata. + */ + readonly [key: string]: any; + + /** + * Create a new notebook document metadata + */ + constructor(); + + /** + * Derived a new document metadata from this metadata. + * + * @param change An object that describes a change to this NotebookDocumentMetadata. + * @return A new NotebookDocumentMetadata that reflects the given change. Will return `this` NotebookDocumentMetadata if the change + * is not changing anything. + */ + with(change: { [key: string]: any }): NotebookDocumentMetadata + } + + /** + * A notebook range represents on ordered pair of two cell indicies. + * It is guaranteed that start is less than or equal to end. + */ + export class NotebookRange { + + /** + * The zero-based start index of this range. + */ + readonly start: number; + + /** + * The exclusive end index of this range (zero-based). + */ + readonly end: number; + + /** + * `true` if `start` and `end` are equal. + */ + readonly isEmpty: boolean; + + /** + * Create a new notebook range. If `start` is not + * before or equal to `end`, the values will be swapped. + * + * @param start start index + * @param end end index. + */ + constructor(start: number, end: number); + + /** + * Derive a new range for this range. + * + * @param change An object that describes a change to this range. + * @return A range that reflects the given change. Will return `this` range if the change + * is not changing anything. + */ + with(change: { start?: number, end?: number }): NotebookRange; + } + + // code specific mime types + // application/x.notebook.error-traceback + // application/x.notebook.stdout + // application/x.notebook.stderr + // application/x.notebook.stream + export class NotebookCellOutputItem { + + // todo@API + // add factory functions for common mime types + // static textplain(value:string): NotebookCellOutputItem; + // static errortrace(value:any): NotebookCellOutputItem; + + /** + * Creates `application/x.notebook.error` + * + * @param err An error for which an output item is wanted + */ + static error(err: Error): NotebookCellOutputItem; + + mime: string; + + //todo@API string or Unit8Array? + // value: string | Uint8Array | unknown; + value: unknown; + + metadata?: { [key: string]: any }; + + constructor(mime: string, value: unknown, metadata?: { [key: string]: any }); + } + + // @jrieken transient + export class NotebookCellOutput { + id: string; + outputs: NotebookCellOutputItem[]; + metadata?: { [key: string]: any }; + constructor(outputs: NotebookCellOutputItem[], metadata?: { [key: string]: any }); + constructor(outputs: NotebookCellOutputItem[], id: string, metadata?: { [key: string]: any }); + } + + /** + * NotebookCellData is the raw representation of notebook cells. Its is part of {@link NotebookData `NotebookData`}. + */ + export class NotebookCellData { + + /** + * The {@link NotebookCellKind kind} of this cell data. + */ + kind: NotebookCellKind; + + /** + * The source value of this cell data - either source code or formatted text. + */ + value: string; + + /** + * The language identifier of the source value of this cell data. Any value from + * {@link languages.getLanguages `getLanguages`} is possible. + */ + languageId: string; + + /** + * The outputs of this cell data. + */ + outputs?: NotebookCellOutput[]; + + /** + * The metadata of this cell data. + */ + metadata?: NotebookCellMetadata; + + /** + * The execution summary of this cell data. + */ + executionSummary?: NotebookCellExecutionSummary; + + /** + * Create new cell data. Minimal cell data specifies its kind, its source value, and the + * language identifier of its source. + * + * @param kind The kind. + * @param value The source value. + * @param languageId The language identifier of the source value. + * @param outputs //TODO@API remove ctor? + * @param metadata //TODO@API remove ctor? + * @param executionSummary //TODO@API remove ctor? + */ + constructor(kind: NotebookCellKind, value: string, languageId: string, outputs?: NotebookCellOutput[], metadata?: NotebookCellMetadata, executionSummary?: NotebookCellExecutionSummary); + } + + /** + * NotebookData is the raw representation of notebooks. + * + * Extensions are responsible to create {@link NotebookData `NotebookData`} so that the editor + * can create a {@link NotebookDocument `NotebookDocument`}. + * + * @see {@link NotebookSerializer} + */ + export class NotebookData { + /** + * The cell data of this notebook data. + */ + cells: NotebookCellData[]; + + /** + * The metadata of this notebook data. + */ + metadata: NotebookDocumentMetadata; + + /** + * Create new notebook data. + * + * @param cells An array of cell data. + * @param metadata Notebook metadata. + */ + constructor(cells: NotebookCellData[], metadata?: NotebookDocumentMetadata); + } + + /** + * The notebook serializer enables the editor to open notebook files. + * + * At its core the editor only knows a {@link NotebookData notebook data structure} but not + * how that data structure is written to a file, nor how it is read from a file. The + * notebook serializer bridges this gap by deserializing bytes into notebook data and + * vice versa. + */ + export interface NotebookSerializer { + + /** + * Deserialize contents of a notebook file into the notebook data structure. + * + * @param content Contents of a notebook file. + * @param token A cancellation token. + * @return Notebook data or a thenable that resolves to such. + */ + deserializeNotebook(content: Uint8Array, token: CancellationToken): NotebookData | Thenable; + + /** + * Serialize notebook data into file contents. + * + * @param data A notebook data structure. + * @param token A cancellation token. + * @returns An array of bytes or a thenable that resolves to such. + */ + serializeNotebook(data: NotebookData, token: CancellationToken): Uint8Array | Thenable; + } + + export interface NotebookDocumentContentOptions { + /** + * Controls if outputs change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit the outputs in the file document, this should be set to true. + */ + transientOutputs?: boolean; + + /** + * Controls if a cell metadata property change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + */ + transientCellMetadata?: { [K in keyof NotebookCellMetadata]?: boolean }; + + /** + * Controls if a document metadata property change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + */ + transientDocumentMetadata?: { [K in keyof NotebookDocumentMetadata]?: boolean }; + } + + export interface NotebookExecuteHandler { + /** + * @param cells The notebook cells to execute. + * @param notebook The notebook for which the execute handler is being called. + * @param controller The controller that the handler is attached to + */ + (this: NotebookController, cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController): void | Thenable + } + + export interface NotebookInterruptHandler { + /** + * @param notebook The notebook for which the interrupt handler is being called. + */ + (this: NotebookController, notebook: NotebookDocument): void | Thenable; + } + + export enum NotebookControllerAffinity { + Default = 1, + Preferred = 2 + } + + // todo@API this is called Controller + export class NotebookKernelPreload { + /** + * APIs that the preload provides to the renderer. These are matched + * against the `dependencies` and `optionalDependencies` arrays in the + * notebook renderer contribution point. + */ + readonly provides: string[]; + + /** + * URI for the file to preload + */ + readonly uri: Uri; + + /** + * @param uri URI for the file to preload + * @param provides Value for the `provides` property + */ + constructor(uri: Uri, provides?: string | string[]); + } + + export interface NotebookCellExecuteStartContext { + /** + * The time that execution began, in milliseconds in the Unix epoch. Used to drive the clock + * that shows for how long a cell has been running. If not given, the clock won't be shown. + */ + startTime?: number; + } + + export interface NotebookCellExecuteEndContext { + /** + * If true, a green check is shown on the cell status bar. + * If false, a red X is shown. + */ + success?: boolean; + + /** + * The time that execution finished, in milliseconds in the Unix epoch. + */ + endTime?: number; + } + + // todo@API jsdoc slightly outdated: kernel, notebook.createNotebookCellExecutionTask + /** + * A NotebookCellExecutionTask is how the kernel modifies a notebook cell as it is executing. When + * {@link notebook.createNotebookCellExecutionTask `createNotebookCellExecutionTask`} is called, the cell + * enters the Pending state. When `start()` is called on the execution task, it enters the Executing state. When + * `end()` is called, it enters the Idle state. While in the Executing state, cell outputs can be + * modified with the methods on the run task. + * + * All outputs methods operate on this NotebookCellExecutionTask's cell by default. They optionally take + * a cellIndex parameter that allows them to modify the outputs of other cells. `appendOutputItems` and + * `replaceOutputItems` operate on the output with the given ID, which can be an output on any cell. They + * all resolve once the output edit has been applied. + */ + export interface NotebookCellExecutionTask { + readonly document: NotebookDocument; + readonly cell: NotebookCell; + readonly token: CancellationToken; + + start(context?: NotebookCellExecuteStartContext): void; + executionOrder: number | undefined; + end(result?: NotebookCellExecuteEndContext): void; + + clearOutput(cellIndex?: number): Thenable; + appendOutput(out: NotebookCellOutput | NotebookCellOutput[], cellIndex?: number): Thenable; + replaceOutput(out: NotebookCellOutput | NotebookCellOutput[], cellIndex?: number): Thenable; + appendOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], outputId: string): Thenable; + replaceOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], outputId: string): Thenable; + } + + export interface NotebookController { + + /** + * The identifier of this notebook controller. + */ + readonly id: string; + + /** + * The notebook view type this controller is for. + */ + readonly viewType: string; + + /** + * An array of language identifiers that are supported by this + * controller. Any language identifier from {@link languages.getLanguages `getLanguages`} + * is possible. When falsy all languages are supported. + * + * Samples: + * ```js + * // support JavaScript and TypeScript + * myController.supportedLanguages = ['javascript', 'typescript'] + * + * // support all languages + * myController.supportedLanguages = undefined; // falsy + * myController.supportedLanguages = []; // falsy + * ``` + */ + supportedLanguages?: string[]; + + /** + * The human-readable label of this notebook controller. + */ + label: string; + + /** + * The human-readable description which is rendered less prominent. + */ + description?: string; + + /** + * The human-readable detail which is rendered less prominent. + */ + detail?: string; + + /** + * Whether this controller supports execution order so that the + * editor can render placeholders for them. + */ + // todo@API rename to supportsExecutionOrder, usesExecutionOrder + hasExecutionOrder?: boolean; + + /** + * The execute handler is invoked when the run gestures in the UI are selected, e.g Run Cell, Run All, + * Run Selection etc. + */ + executeHandler: NotebookExecuteHandler; + + /** + * The interrupt handler is invoked the interrupt all execution. This is contrary to cancellation (available via + * [`NotebookCellExecutionTask#token`](NotebookCellExecutionTask#token)) and should only be used when + * execution-level cancellation is supported + */ + interruptHandler?: NotebookInterruptHandler + + /** + * Dispose and free associated resources. + */ + dispose(): void; + + /** + * An event that fires whenever a controller has been selected for a notebook document. Selecting a controller + * for a notebook is a user gesture and happens either explicitly or implicitly when interacting while a + * controller was suggested. + */ + readonly onDidChangeNotebookAssociation: Event<{ notebook: NotebookDocument, selected: boolean }>; + + /** + * A controller can set affinities for specific notebook documents. This allows a controller + * to be more important for some notebooks. + * + * @param notebook The notebook for which a priority is set. + * @param affinity A controller affinity + */ + updateNotebookAffinity(notebook: NotebookDocument, affinity: NotebookControllerAffinity): void; + + /** + * Create a cell execution task. + * + * This should be used in response to the {@link NotebookController.executeHandler execution handler} + * being calleed or when cell execution has been started else, e.g when a cell was already + * executing or when cell execution was triggered from another source. + * + * @param cell The notebook cell for which to create the execution. + * @returns A notebook cell execution. + */ + createNotebookCellExecutionTask(cell: NotebookCell): NotebookCellExecutionTask; + + // todo@API find a better name than "preloads" + // todo@API allow add, not remove + // ipc + readonly preloads: NotebookKernelPreload[]; + + /** + * An event that fires when a renderer (see `preloads`) has send a message to the controller. + */ + readonly onDidReceiveMessage: Event<{ editor: NotebookEditor, message: any }>; + + /** + * Send a message to the renderer of notebook editors. + * + * Note that only editors showing documents that are bound to this controller + * are receiving the message. + * + * @param message The message to send. + * @param editor A specific editor to send the message to. When `undefined` all applicable editors are receiving the message. + * @returns A promise that resolves to a boolean indicating if the message has been send or not. + */ + postMessage(message: any, editor?: NotebookEditor): Thenable; + + //todo@API validate this works + asWebviewUri(localResource: Uri): Uri; + } + + export enum NotebookCellExecutionState { + Idle = 1, + Pending = 2, + Executing = 3, + } + + export interface NotebookCellExecutionStateChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cell execution state has changed. + */ + readonly document: NotebookDocument; + readonly cell: NotebookCell; + readonly executionState: NotebookCellExecutionState; + } + + /** + * Represents the alignment of status bar items. + */ + export enum NotebookCellStatusBarAlignment { + + /** + * Aligned to the left side. + */ + Left = 1, + + /** + * Aligned to the right side. + */ + Right = 2 + } + + export class NotebookCellStatusBarItem { + text: string; + alignment: NotebookCellStatusBarAlignment; + command?: string | Command; + tooltip?: string; + priority?: number; + accessibilityInformation?: AccessibilityInformation; + + constructor(text: string, alignment: NotebookCellStatusBarAlignment, command?: string | Command, tooltip?: string, priority?: number, accessibilityInformation?: AccessibilityInformation); + } + + export interface NotebookCellStatusBarItemProvider { + /** + * Implement and fire this event to signal that statusbar items have changed. The provide method will be called again. + */ + onDidChangeCellStatusBarItems?: Event; + + /** + * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state. + */ + provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult; + } + + export namespace notebook { + + /** + * All notebook documents currently known to the editor. + */ + export const notebookDocuments: ReadonlyArray; + + /** + * 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. + * + * *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. + * + * *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. + * + * @param uri The resource to open. + * @returns A promise that resolves to a {@link NotebookDocument notebook} + */ + export function openNotebookDocument(uri: Uri): Thenable; + + /** + * Open an untitled notebook. The editor will prompt the user for a file + * path when the document is to be saved. + * + * @see {@link openNotebookDocument} + * @param viewType The notebook view type that should be used. + * @param content The initial contents of the notebook. + * @returns A promise that resolves to a {@link NotebookDocument notebook}. + */ + export function openNotebookDocument(viewType: string, content?: NotebookData): Thenable; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is opened. + */ + export const onDidOpenNotebookDocument: Event; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is disposed. + * + * *Note 1:* There is no guarantee that this event fires when an editor tab is closed. + * + * *Note 2:* A notebook can be open but not shown in an editor which means this event can fire + * for a notebook that has not been shown in an editor. + */ + export const onDidCloseNotebookDocument: Event; + + /** + * Register a {@link NotebookSerializer notebook serializer}. + * + * A notebook serializer must to be contributed through the `notebooks` extension point. When opening a notebook file, the editor will send + * the `onNotebook:` activation event, and extensions must register their serializer in return. + * + * @param notebookType A notebook. + * @param serializer A notebook serialzier. + * @param options Optional context options that define what parts of a notebook should be persisted + * @return A {@link Disposable} that unregisters this serializer when being disposed. + */ + export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable; + + /** + * Creates a new notebook controller. + * + * @param id Identifier of the controller. Must be unique per extension. + * @param viewType A notebook view type for which this controller is for. + * @param label The label of the controller + * @param handler + * @param preloads + */ + export function createNotebookController(id: string, viewType: string, label: string, handler?: NotebookExecuteHandler, preloads?: NotebookKernelPreload[]): NotebookController; + + // todo@API what is this used for? + // todo@API qualify cell, ...NotebookCell... + export const onDidChangeNotebookCellExecutionState: Event; + + export function registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditor + + export enum NotebookEditorRevealType { + /** + * The range will be revealed with as little scrolling as possible. + */ + Default = 0, + + /** + * The range will always be revealed in the center of the viewport. + */ + InCenter = 1, + + /** + * If the range is outside the viewport, it will be revealed in the center of the viewport. + * Otherwise, it will be revealed with as little scrolling as possible. + */ + InCenterIfOutsideViewport = 2, + + /** + * The range will always be revealed at the top of the viewport. + */ + AtTop = 3 + } + + export interface NotebookEditor { + /** + * The document associated with this notebook editor. + */ + readonly document: NotebookDocument; + + /** + * The selections on this notebook editor. + * + * The primary selection (or focused range) is `selections[0]`. When the document has no cells, the primary selection is empty `{ start: 0, end: 0 }`; + */ + readonly selections: NotebookRange[]; + + /** + * The current visible ranges in the editor (vertically). + */ + readonly visibleRanges: NotebookRange[]; + + /** + * Scroll as indicated by `revealType` in order to reveal the given range. + * + * @param range A range. + * @param revealType The scrolling strategy for revealing `range`. + */ + revealRange(range: NotebookRange, revealType?: NotebookEditorRevealType): void; + + /** + * The column in which this editor shows. + */ + readonly viewColumn?: ViewColumn; + } + + export interface NotebookDocumentMetadataChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the document metadata have changed. + */ + readonly document: NotebookDocument; + } + + export interface NotebookCellsChangeData { + readonly start: number; + // todo@API end? Use NotebookCellRange instead? + readonly deletedCount: number; + // todo@API removedCells, deletedCells? + readonly deletedItems: NotebookCell[]; + // todo@API addedCells, insertedCells, newCells? + readonly items: NotebookCell[]; + } + + export interface NotebookCellsChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cells have changed. + */ + readonly document: NotebookDocument; + readonly changes: ReadonlyArray; + } + + export interface NotebookCellOutputsChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cell outputs have changed. + */ + readonly document: NotebookDocument; + readonly cells: NotebookCell[]; + } + + export interface NotebookCellMetadataChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cell metadata have changed. + */ + readonly document: NotebookDocument; + readonly cell: NotebookCell; + } + + export interface NotebookEditorSelectionChangeEvent { + /** + * The {@link NotebookEditor notebook editor} for which the selections have changed. + */ + readonly notebookEditor: NotebookEditor; + readonly selections: ReadonlyArray + } + + export interface NotebookEditorVisibleRangesChangeEvent { + /** + * The {@link NotebookEditor notebook editor} for which the visible ranges have changed. + */ + readonly notebookEditor: NotebookEditor; + readonly visibleRanges: ReadonlyArray; + } + + + export interface NotebookDocumentShowOptions { + viewColumn?: ViewColumn; + preserveFocus?: boolean; + preview?: boolean; + selections?: NotebookRange[]; + } + + export namespace notebook { + + + + export const onDidSaveNotebookDocument: Event; + + export const onDidChangeNotebookDocumentMetadata: Event; + export const onDidChangeNotebookCells: Event; + + // todo@API add onDidChangeNotebookCellOutputs + export const onDidChangeCellOutputs: Event; + + // todo@API add onDidChangeNotebookCellMetadata + export const onDidChangeCellMetadata: Event; + } + + export namespace window { + export const visibleNotebookEditors: NotebookEditor[]; + export const onDidChangeVisibleNotebookEditors: Event; + export const activeNotebookEditor: NotebookEditor | undefined; + export const onDidChangeActiveNotebookEditor: Event; + export const onDidChangeNotebookEditorSelection: Event; + export const onDidChangeNotebookEditorVisibleRanges: Event; + + export function showNotebookDocument(uri: Uri, options?: NotebookDocumentShowOptions): Thenable; + export function showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorEdit + + // todo@API add NotebookEdit-type which handles all these cases? + // export class NotebookEdit { + // range: NotebookRange; + // newCells: NotebookCellData[]; + // newMetadata?: NotebookDocumentMetadata; + // constructor(range: NotebookRange, newCells: NotebookCellData) + // } + + // export class NotebookCellEdit { + // newMetadata?: NotebookCellMetadata; + // } + + // export interface WorkspaceEdit { + // set(uri: Uri, edits: TextEdit[] | NotebookEdit[]): void + // } + + export interface WorkspaceEdit { + // todo@API add NotebookEdit-type which handles all these cases? + replaceNotebookMetadata(uri: Uri, value: NotebookDocumentMetadata): void; + replaceNotebookCells(uri: Uri, range: NotebookRange, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void; + replaceNotebookCellMetadata(uri: Uri, index: number, cellMetadata: NotebookCellMetadata, metadata?: WorkspaceEditEntryMetadata): void; + } + + export interface NotebookEditorEdit { + replaceMetadata(value: NotebookDocumentMetadata): void; + replaceCells(start: number, end: number, cells: NotebookCellData[]): void; + replaceCellMetadata(index: number, metadata: NotebookCellMetadata): void; + } + + export interface NotebookEditor { + /** + * Perform an edit on the notebook associated with this notebook editor. + * + * The given callback-function is invoked with an {@link NotebookEditorEdit edit-builder} which must + * be used to make edits. Note that the edit-builder is only valid while the + * callback executes. + * + * @param callback A function which can create edits using an {@link NotebookEditorEdit edit-builder}. + * @return A promise that resolves with a value indicating if the edits could be applied. + */ + // @jrieken REMOVE maybe + edit(callback: (editBuilder: NotebookEditorEdit) => void): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorDecorationType + + export interface NotebookEditor { + setDecorations(decorationType: NotebookEditorDecorationType, range: NotebookRange): void; + } + + export interface NotebookDecorationRenderOptions { + backgroundColor?: string | ThemeColor; + borderColor?: string | ThemeColor; + top: ThemableDecorationAttachmentRenderOptions; + } + + export interface NotebookEditorDecorationType { + readonly key: string; + dispose(): void; + } + + export namespace notebook { + export function createNotebookEditorDecorationType(options: NotebookDecorationRenderOptions): NotebookEditorDecorationType; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookConcatTextDocument + + export namespace notebook { + /** + * Create a document that is the concatenation of all notebook cells. By default all code-cells are included + * but a selector can be provided to narrow to down the set of cells. + * + * @param notebook + * @param selector + */ + // todo@API really needed? we didn't find a user here + export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument; + } + + export interface NotebookConcatTextDocument { + readonly uri: Uri; + readonly isClosed: boolean; + dispose(): void; + readonly onDidChange: Event; + readonly version: number; + getText(): string; + getText(range: Range): string; + + offsetAt(position: Position): number; + positionAt(offset: number): Position; + validateRange(range: Range): Range; + validatePosition(position: Position): Position; + + locationAt(positionOrRange: Position | Range): Location; + positionAt(location: Location): Position; + contains(uri: Uri): boolean; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, NotebookContentProvider + + + interface NotebookDocumentBackup { + /** + * Unique identifier for the backup. + * + * This id is passed back to your extension in `openNotebook` when opening a notebook editor from a backup. + */ + readonly id: string; + + /** + * Delete the current backup. + * + * This is called by VS Code when it is clear the current backup is no longer needed, such as when a new backup + * is made or when the file is saved. + */ + delete(): void; + } + + interface NotebookDocumentBackupContext { + readonly destination: Uri; + } + + interface NotebookDocumentOpenContext { + readonly backupId?: string; + readonly untitledDocumentData?: Uint8Array; + } + + // todo@API use openNotebookDOCUMENT to align with openCustomDocument etc? + // todo@API rename to NotebookDocumentContentProvider + export interface NotebookContentProvider { + + readonly options?: NotebookDocumentContentOptions; + readonly onDidChangeNotebookContentOptions?: Event; + + /** + * Content providers should always use {@link FileSystemProvider file system providers} to + * resolve the raw content for `uri` as the resouce is not necessarily a file on disk. + */ + openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext, token: CancellationToken): NotebookData | Thenable; + + // todo@API use NotebookData instead + saveNotebook(document: NotebookDocument, token: CancellationToken): Thenable; + + // todo@API use NotebookData instead + saveNotebookAs(targetResource: Uri, document: NotebookDocument, token: CancellationToken): Thenable; + + // todo@API use NotebookData instead + backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, token: CancellationToken): Thenable; + } + + export namespace notebook { + + // TODO@api use NotebookDocumentFilter instead of just notebookType:string? + // TODO@API options duplicates the more powerful variant on NotebookContentProvider + export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions): Disposable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, LiveShare + + export interface NotebookRegistrationData { + displayName: string; + filenamePattern: (GlobPattern | { include: GlobPattern; exclude: GlobPattern; })[]; + exclusive?: boolean; + } + + export namespace notebook { + // SPECIAL overload with NotebookRegistrationData + export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions, registrationData?: NotebookRegistrationData): Disposable; + // SPECIAL overload with NotebookRegistrationData + export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions, registration?: NotebookRegistrationData): Disposable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/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`. + */ + parameters?: string; + + /** + * The fully qualified name, like package name or file path. Rendered after `signature`. + */ + qualifier?: string; + + /** + * The return-type of a function or type of a property/variable. Rendered rightmost. + */ + type?: string; + } + + //#endregion + + //#region @eamodio - timeline: https://github.com/microsoft/vscode/issues/84297 + + export class TimelineItem { + /** + * A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred. + */ + timestamp: number; + + /** + * A human-readable string describing the timeline item. + */ + label: string; + + /** + * Optional id for the timeline item. It must be unique across all the timeline items provided by this source. + * + * If not provided, an id is generated using the timeline item's timestamp. + */ + id?: string; + + /** + * The icon path or {@link ThemeIcon} for the timeline item. + */ + iconPath?: Uri | { light: Uri; dark: Uri; } | ThemeIcon; + + /** + * A human readable string describing less prominent details of the timeline item. + */ + description?: string; + + /** + * The tooltip text when you hover over the timeline item. + */ + detail?: string; + + /** + * The {@link Command} that should be executed when the timeline item is selected. + */ + command?: Command; + + /** + * Context value of the timeline item. This can be used to contribute specific actions to the item. + * For example, a timeline item is given a context value as `commit`. When contributing actions to `timeline/item/context` + * using `menus` extension point, you can specify context value for key `timelineItem` in `when` expression like `timelineItem == commit`. + * ``` + * "contributes": { + * "menus": { + * "timeline/item/context": [ + * { + * "command": "extension.copyCommitId", + * "when": "timelineItem == commit" + * } + * ] + * } + * } + * ``` + * This will show the `extension.copyCommitId` action only for items where `contextValue` is `commit`. + */ + contextValue?: string; + + /** + * Accessibility information used when screen reader interacts with this timeline item. + */ + accessibilityInformation?: AccessibilityInformation; + + /** + * @param label A human-readable string describing the timeline item + * @param timestamp A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred + */ + constructor(label: string, timestamp: number); + } + + export interface TimelineChangeEvent { + /** + * The {@link Uri} of the resource for which the timeline changed. + */ + uri: Uri; + + /** + * A flag which indicates whether the entire timeline should be reset. + */ + reset?: boolean; + } + + export interface Timeline { + readonly paging?: { + /** + * A provider-defined cursor specifying the starting point of timeline items which are after the ones returned. + * Use `undefined` to signal that there are no more items to be returned. + */ + readonly cursor: string | undefined; + }; + + /** + * An array of {@link TimelineItem timeline items}. + */ + readonly items: readonly TimelineItem[]; + } + + export interface TimelineOptions { + /** + * A provider-defined cursor specifying the starting point of the timeline items that should be returned. + */ + cursor?: string; + + /** + * An optional maximum number timeline items or the all timeline items newer (inclusive) than the timestamp or id that should be returned. + * If `undefined` all timeline items should be returned. + */ + limit?: number | { timestamp: number; id?: string; }; + } + + export interface TimelineProvider { + /** + * An optional event to signal that the timeline for a source has changed. + * To signal that the timeline for all resources (uris) has changed, do not pass any argument or pass `undefined`. + */ + onDidChange?: Event; + + /** + * An identifier of the source of the timeline items. This can be used to filter sources. + */ + readonly id: string; + + /** + * A human-readable string describing the source of the timeline items. This can be used as the display label when filtering sources. + */ + readonly label: string; + + /** + * Provide {@link TimelineItem timeline items} for a {@link Uri}. + * + * @param uri The {@link Uri} of the file to provide the timeline for. + * @param options A set of options to determine how results should be returned. + * @param token A cancellation token. + * @return The {@link TimelineResult timeline result} or a thenable that resolves to such. The lack of a result + * can be signaled by returning `undefined`, `null`, or an empty array. + */ + provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * Register a timeline provider. + * + * Multiple providers can be registered. In that case, providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents. + * @param provider A timeline provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/91555 + + export enum StandardTokenType { + Other = 0, + Comment = 1, + String = 2, + RegEx = 4 + } + + export interface TokenInformation { + type: StandardTokenType; + range: Range; + } + + export namespace languages { + export function getTokenInformationAtPosition(document: TextDocument, position: Position): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/16221 + + // todo@API Split between Inlay- and OverlayHints (InlayHint are for a position, OverlayHints for a non-empty range) + // todo@API add "mini-markdown" for links and styles + // (done) remove description + // (done) rename to InlayHint + // (done) add InlayHintKind with type, argument, etc + + export namespace languages { + /** + * Register a inlay hints provider. + * + * Multiple providers can be registered for a language. In that case providers are asked in + * parallel and the results are merged. A failing provider (rejected promise or exception) will + * not cause a failure of the whole operation. + * + * @param selector A selector that defines the documents this provider is applicable to. + * @param provider An inlay hints provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider): Disposable; + } + + export enum InlayHintKind { + Other = 0, + Type = 1, + Parameter = 2, + } + + /** + * Inlay hint information. + */ + export class InlayHint { + /** + * The text of the hint. + */ + text: string; + /** + * The position of this hint. + */ + position: Position; + /** + * The kind of this hint. + */ + kind?: InlayHintKind; + /** + * Whitespace before the hint. + */ + whitespaceBefore?: boolean; + /** + * Whitespace after the hint. + */ + whitespaceAfter?: boolean; + + // todo@API make range first argument + constructor(text: string, position: Position, kind?: InlayHintKind); + } + + /** + * The inlay hints provider interface defines the contract between extensions and + * the inlay hints feature. + */ + export interface InlayHintsProvider { + + /** + * An optional event to signal that inlay hints have changed. + * @see {@link EventEmitter} + */ + onDidChangeInlayHints?: Event; + + /** + * + * @param model The document in which the command was invoked. + * @param range The range for which inlay hints should be computed. + * @param token A cancellation token. + * @return A list of inlay hints or a thenable that resolves to such. + */ + provideInlayHints(model: TextDocument, range: Range, token: CancellationToken): ProviderResult; + } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/104436 + + export enum ExtensionRuntime { + /** + * The extension is running in a NodeJS extension host. Runtime access to NodeJS APIs is available. + */ + Node = 1, + /** + * The extension is running in a Webworker extension host. Runtime access is limited to Webworker APIs. + */ + Webworker = 2 + } + + export interface ExtensionContext { + readonly extensionRuntime: ExtensionRuntime; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/102091 + + export interface TextDocument { + + /** + * The {@link NotebookDocument notebook} that contains this document as a notebook cell or `undefined` when + * the document is not contained by a notebook (this should be the more frequent case). + */ + notebook: NotebookDocument | undefined; + } + //#endregion + + //#region 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; + + /** + * Requests that tests be run by their controller. + * @param run Run options to use + * @param token Cancellation token for the test run + */ + export function runTests(run: TestRunRequest, token?: CancellationToken): Thenable; + + /** + * Returns an observer that 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; + + /** + * 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 VS Code. 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} + */ + 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; + + /** + * List of test results stored by VS Code, sorted in descnding + * 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>; + + /** + * An event that fires when an existing test in the collection changes, or + * null if a top-level test was added or removed. When fired, the consumer + * should check the test item and all its children for changes. + */ + readonly onDidChangeTest: Event; + + /** + * 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 VS Code to eventually tell test + * providers that they no longer need to update tests. + */ + dispose(): void; + } + + /** + * @stability experimental + */ + export interface TestsChangeEvent { + /** + * List of all tests that are newly added. + */ + readonly added: ReadonlyArray>; + + /** + * List of existing tests that have updated. + */ + readonly updated: ReadonlyArray>; + + /** + * List of existing tests that have been removed. + */ + readonly removed: ReadonlyArray>; + } + + /** + * Interface to discover and execute tests. + */ + 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>; + + /** + * 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. + * + * @param options Options for this test run + * @param cancellationToken Token that signals the used asked to abort the test run. + */ + runTests(options: TestRunRequest, token: CancellationToken): Thenable | void; + } + + /** + * Options given to {@link test.runTests}. + */ + export interface TestRunRequest { + /** + * 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}. + */ + tests: TestItem[]; + + /** + * An array of tests the user has marked as excluded in VS Code. May be + * omitted if no exclusions were requested. Test controllers should not run + * excluded tests or any children of excluded tests. + */ + exclude?: TestItem[]; + + /** + * Whether tests in this run should be debugged. + */ + debug: boolean; + } + + /** + * 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; + + /** + * 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 VS Code 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 { + /** + * Unique identifier that matches that of the associated TestItem. + * This is used to correlate test results and tests in the document with + * those in the workspace (test explorer). + */ + readonly id: string; + + /** + * URI this TestItem is associated with. May be a file or file. + */ + readonly uri?: Uri; + + /** + * Display name describing the test case. + */ + readonly label: string; + + /** + * Optional description that appears next to the label. + */ + readonly description?: string; + + /** + * Location of the test item in its `uri`. This is only meaningful if the + * `uri` points to a file. + */ + readonly range?: Range; + + /** + * State of the test in each task. In the common case, a test will only + * be executed in a single task and the length of this array will be 1. + */ + readonly taskStates: ReadonlyArray; + + /** + * Optional list of nested tests for this item. + */ + readonly children: Readonly[]; + } + + export interface TestSnapshoptTaskState { + /** + * Current result of the test. + */ + readonly state: TestResultState; + + /** + * The number of milliseconds the test took to run. This is set once the + * `state` is `Passed`, `Failed`, or `Errored`. + */ + readonly duration?: number; + + /** + * Associated test run message. Can, for example, contain assertion + * failure information if the test fails. + */ + readonly messages: ReadonlyArray; + } + + //#endregion + + //#region Opener service (https://github.com/microsoft/vscode/issues/109277) + + /** + * Details if an `ExternalUriOpener` can open a uri. + * + * The priority is also used to rank multiple openers against each other and determine + * if an opener should be selected automatically or if the user should be prompted to + * select an opener. + * + * VS Code will try to use the best available opener, as sorted by `ExternalUriOpenerPriority`. + * If there are multiple potential "best" openers for a URI, then the user will be prompted + * to select an opener. + */ + export enum ExternalUriOpenerPriority { + /** + * The opener is disabled and will never be shown to users. + * + * Note that the opener can still be used if the user specifically + * configures it in their settings. + */ + None = 0, + + /** + * The opener can open the uri but will not cause a prompt on its own + * since VS Code always contributes a built-in `Default` opener. + */ + Option = 1, + + /** + * The opener can open the uri. + * + * VS Code's built-in opener has `Default` priority. This means that any additional `Default` + * openers will cause the user to be prompted to select from a list of all potential openers. + */ + Default = 2, + + /** + * The opener can open the uri and should be automatically selected over any + * default openers, include the built-in one from VS Code. + * + * A preferred opener will be automatically selected if no other preferred openers + * are available. If multiple preferred openers are available, then the user + * is shown a prompt with all potential openers (not just preferred openers). + */ + Preferred = 3, + } + + /** + * Handles opening uris to external resources, such as http(s) links. + * + * Extensions can implement an `ExternalUriOpener` to open `http` links to a webserver + * inside of VS Code instead of having the link be opened by the web browser. + * + * Currently openers may only be registered for `http` and `https` uris. + */ + export interface ExternalUriOpener { + + /** + * Check if the opener can open a uri. + * + * @param uri The uri being opened. This is the uri that the user clicked on. It has + * not yet gone through port forwarding. + * @param token Cancellation token indicating that the result is no longer needed. + * + * @return Priority indicating if the opener can open the external uri. + */ + canOpenExternalUri(uri: Uri, token: CancellationToken): ExternalUriOpenerPriority | Thenable; + + /** + * Open a uri. + * + * This is invoked when: + * + * - The user clicks a link which does not have an assigned opener. In this case, first `canOpenExternalUri` + * is called and if the user selects this opener, then `openExternalUri` is called. + * - The user sets the default opener for a link in their settings and then visits a link. + * + * @param resolvedUri The uri to open. This uri may have been transformed by port forwarding, so it + * may not match the original uri passed to `canOpenExternalUri`. Use `ctx.originalUri` to check the + * original uri. + * @param ctx Additional information about the uri being opened. + * @param token Cancellation token indicating that opening has been canceled. + * + * @return Thenable indicating that the opening has completed. + */ + openExternalUri(resolvedUri: Uri, ctx: OpenExternalUriContext, token: CancellationToken): Thenable | void; + } + + /** + * Additional information about the uri being opened. + */ + interface OpenExternalUriContext { + /** + * The uri that triggered the open. + * + * This is the original uri that the user clicked on or that was passed to `openExternal.` + * Due to port forwarding, this may not match the `resolvedUri` passed to `openExternalUri`. + */ + readonly sourceUri: Uri; + } + + /** + * Additional metadata about a registered `ExternalUriOpener`. + */ + interface ExternalUriOpenerMetadata { + + /** + * List of uri schemes the opener is triggered for. + * + * Currently only `http` and `https` are supported. + */ + readonly schemes: readonly string[] + + /** + * Text displayed to the user that explains what the opener does. + * + * For example, 'Open in browser preview' + */ + readonly label: string; + } + + namespace window { + /** + * Register a new `ExternalUriOpener`. + * + * When a uri is about to be opened, an `onOpenExternalUri:SCHEME` activation event is fired. + * + * @param id Unique id of the opener, such as `myExtension.browserPreview`. This is used in settings + * and commands to identify the opener. + * @param opener Opener to register. + * @param metadata Additional information about the opener. + * + * @returns Disposable that unregisters the opener. + */ + export function registerExternalUriOpener(id: string, opener: ExternalUriOpener, metadata: ExternalUriOpenerMetadata): Disposable; + } + + interface OpenExternalOptions { + /** + * Allows using openers contributed by extensions through `registerExternalUriOpener` + * when opening the resource. + * + * If `true`, VS Code will check if any contributed openers can handle the + * uri, and fallback to the default opener behavior. + * + * If it is string, this specifies the id of the `ExternalUriOpener` + * that should be used if it is available. Use `'default'` to force VS Code's + * standard external opener to be used. + */ + readonly allowContributedOpeners?: boolean | string; + } + + namespace env { + export function openExternal(target: Uri, options?: OpenExternalOptions): Thenable; + } + + //#endregion + + //#region https://github.com/Microsoft/vscode/issues/15178 + + // TODO@API must be a class + export interface OpenEditorInfo { + name: string; + resource: Uri; + isActive: boolean; + } + + export namespace window { + export const openEditors: ReadonlyArray; + + // todo@API proper event type + export const onDidChangeOpenEditors: Event; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/120173 + /** + * The object describing the properties of the workspace trust request + */ + export interface WorkspaceTrustRequestOptions { + /** + * Custom message describing the user action that requires workspace + * trust. If omitted, a generic message will be displayed in the workspace + * trust request dialog. + */ + readonly message?: string; + } + + export namespace workspace { + /** + * Prompt the user to chose whether to trust the current workspace + * @param options Optional object describing the properties of the + * workspace trust request. + */ + export function requestWorkspaceTrust(options?: WorkspaceTrustRequestOptions): Thenable; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/115616 @alexr00 + export enum PortAutoForwardAction { + Notify = 1, + OpenBrowser = 2, + OpenPreview = 3, + Silent = 4, + Ignore = 5 + } + + export class PortAttributes { + /** + * The port number associated with this this set of attributes. + */ + port: number; + + /** + * The action to be taken when this port is detected for auto forwarding. + */ + autoForwardAction: PortAutoForwardAction; + + /** + * Creates a new PortAttributes object + * @param port the port number + * @param autoForwardAction the action to take when this port is detected + */ + constructor(port: number, autoForwardAction: PortAutoForwardAction); + } + + export interface PortAttributesProvider { + /** + * Provides attributes for the given port. For ports that your extension doesn't know about, simply + * return undefined. For example, if `providePortAttributes` is called with ports 3000 but your + * extension doesn't know anything about 3000 you should return undefined. + */ + providePortAttributes(port: number, pid: number | undefined, commandLine: string | undefined, token: CancellationToken): ProviderResult; + } + + export namespace workspace { + /** + * If your extension listens on ports, consider registering a PortAttributesProvider to provide information + * about the ports. For example, a debug extension may know about debug ports in it's debuggee. By providing + * this information with a PortAttributesProvider the extension can tell VS Code that these ports should be + * ignored, since they don't need to be user facing. + * + * @param portSelector If registerPortAttributesProvider is called after you start your process then you may already + * know the range of ports or the pid of your process. All properties of a the portSelector must be true for your + * provider to get called. + * The `portRange` is start inclusive and end exclusive. + * @param provider The PortAttributesProvider + */ + export function registerPortAttributesProvider(portSelector: { pid?: number, portRange?: [number, number], commandMatcher?: RegExp }, provider: PortAttributesProvider): Disposable; + } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/119904 @eamodio + + export interface SourceControlInputBox { + + /** + * Sets focus to the input. + */ + focus(): void; + } + + //#endregion + + //#region FileSystemProvider stat readonly - https://github.com/microsoft/vscode/issues/73122 + + 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 + */ + export interface FileStat { + + /** + * 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; + } + + //#endregion + + //#region Expose parent session on DebugSessions - https://github.com/microsoft/vscode/issues/123403#issuecomment-843269200 + + export interface DebugSession { + /** + * The parent session of this debug session, if it was created as a child. + * @see DebugSessionOptions.parentSession + */ + readonly parentSession?: DebugSession; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/87110 @eamodio + + export interface Memento { + + /** + * The stored keys. + */ + readonly keys: readonly string[]; + } + + //#endregion } From 9120e3d956255357261ed74d21bd3af55ee22fbb Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 14:27:59 -0700 Subject: [PATCH 02/11] new API --- vscode.d.ts | 247 ++++++++++++++++--------------------------- vscode.proposed.d.ts | 35 ++++-- 2 files changed, 115 insertions(+), 167 deletions(-) diff --git a/vscode.d.ts b/vscode.d.ts index f9a4ddc9a18..74f694427a2 100644 --- a/vscode.d.ts +++ b/vscode.d.ts @@ -9857,7 +9857,7 @@ declare module 'vscode' { readonly onDidTriggerButton: Event; /** - * Items to pick from. + * Items to pick from. This can be read and updated by the extension. */ items: readonly T[]; @@ -10639,6 +10639,65 @@ declare module 'vscode' { */ export const onDidSaveTextDocument: Event; + /** + * All notebook documents currently known to the editor. + */ + export const notebookDocuments: readonly NotebookDocument[]; + + /** + * 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. + * + * *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. + * + * *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. + * + * @param uri The resource to open. + * @returns A promise that resolves to a {@link NotebookDocument notebook} + */ + export function openNotebookDocument(uri: Uri): Thenable; + + /** + * Open an untitled notebook. The editor will prompt the user for a file + * path when the document is to be saved. + * + * @see {@link openNotebookDocument} + * @param notebookType The notebook type that should be used. + * @param content The initial contents of the notebook. + * @returns A promise that resolves to a {@link NotebookDocument notebook}. + */ + export function openNotebookDocument(notebookType: string, content?: NotebookData): Thenable; + + /** + * Register a {@link NotebookSerializer notebook serializer}. + * + * A notebook serializer must be contributed through the `notebooks` extension point. When opening a notebook file, the editor will send + * the `onNotebook:` activation event, and extensions must register their serializer in return. + * + * @param notebookType A notebook. + * @param serializer A notebook serialzier. + * @param options Optional context options that define what parts of a notebook should be persisted + * @return A {@link Disposable} that unregisters this serializer when being disposed. + */ + export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is opened. + */ + export const onDidOpenNotebookDocument: Event; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is disposed. + * + * *Note 1:* There is no guarantee that this event fires when an editor tab is closed. + * + * *Note 2:* A notebook can be open but not shown in an editor which means this event can fire + * for a notebook that has not been shown in an editor. + */ + export const onDidCloseNotebookDocument: Event; + /** * An event that is emitted when files are being created. * @@ -11371,10 +11430,6 @@ declare module 'vscode' { */ readonly uri: Uri; - /** @deprecated */ - // todo@API remove - readonly viewType: string; - /** * The type of notebook. */ @@ -11454,16 +11509,9 @@ declare module 'vscode' { readonly success?: boolean; /** - * The unix timestamp at which execution started. + * The times at which execution started and ended, as unix timestamps */ - // @rob - //todo@API think about invalid state (no end, but start and vice versa) - readonly startTime?: number; - - /** - * The unix timestamp at which execution ended. - */ - readonly endTime?: number; + readonly timing?: { startTime: number, endTime: number }; } /** @@ -11564,7 +11612,7 @@ declare module 'vscode' { static error(value: Error): NotebookCellOutputItem; /** - * The mime type which determines how the {@link NotebookCellOutputItem.value `value`}-property + * The mime type which determines how the {@link NotebookCellOutputItem.data `data`}-property * is interpreted. * * Notebooks have built-in support for certain mime-types, extensions can add support for new @@ -11591,15 +11639,8 @@ declare module 'vscode' { * {@link NotebookCellOutputItem output items} where contained items represent the same result but * use different MIME types. */ - //todo@API - add sugar function to add more outputs export class NotebookCellOutput { - /** - * Identifier for this output. Using the identifier allows a subsequent execution to modify - * existing output. Defaults to a fresh UUID. - */ - id: string; - /** * The output items of this output. Each item must represent the same result. _Note_ that repeated * MIME types per output is invalid and that the editor will just pick one of them. @@ -11620,24 +11661,13 @@ declare module 'vscode' { */ metadata?: { [key: string]: any }; - /** - * Create new notebook output. - * - * @param outputs Notebook output items. - * @param metadata Optional metadata. - */ - constructor(outputs: NotebookCellOutputItem[], metadata?: { [key: string]: any }); - /** * Create new notebook output. * * @param items Notebook output items. - * @param id Identifier of this output. * @param metadata Optional metadata. */ - //todo@API id-args is not used by jupyter but we it added with display_id in mind... - // @jupyter check if needed - constructor(items: NotebookCellOutputItem[], id: string, metadata?: { [key: string]: any }); + constructor(items: NotebookCellOutputItem[], metadata?: { [key: string]: any }); } /** @@ -11683,12 +11713,8 @@ declare module 'vscode' { * @param kind The kind. * @param value The source value. * @param languageId The language identifier of the source value. - * @param outputs Optional outputs. - * @param metadata Optional metadata. - * @param executionSummary Optional execution summary. */ - // todo@API should ctors only have the args for required properties? - constructor(kind: NotebookCellKind, value: string, languageId: string, outputs?: NotebookCellOutput[], metadata?: { [key: string]: any }, executionSummary?: NotebookCellExecutionSummary); + constructor(kind: NotebookCellKind, value: string, languageId: string); } /** @@ -11824,10 +11850,6 @@ declare module 'vscode' { */ readonly id: string; - // todo@api remove - /** @deprecated */ - readonly viewType: string; - /** * The notebook type this controller is for. */ @@ -11871,10 +11893,6 @@ declare module 'vscode' { */ supportsExecutionOrder?: boolean; - // todo@API remove - /** @deprecated */ - hasExecutionOrder?: boolean; - /** * Create a cell execution task. * @@ -11933,32 +11951,6 @@ declare module 'vscode' { dispose(): void; } - // todo@api jsdoc - // todo@api Inline unless we can come up with more (future) properties - export interface NotebookCellExecuteStartContext { - /** - * The time that execution began, in milliseconds in the Unix epoch. Used to drive the clock - * that shows for how long a cell has been running. If not given, the clock won't be shown. - */ - startTime?: number; - } - - // todo@api jsdoc - // todo@api Inline unless we can come up with more (future) properties - export interface NotebookCellExecuteEndContext { - /** - * If true, a green check is shown on the cell status bar. - * If false, a red X is shown. - * If undefined, no check or X icon is shown. - */ - success?: boolean; - - /** - * The time that execution finished, in milliseconds in the Unix epoch. - */ - endTime?: number; - } - /** * A NotebookCellExecution is how {@link NotebookController notebook controller} modify a notebook cell as * it is executing. @@ -11988,13 +11980,23 @@ declare module 'vscode' { */ executionOrder: number | undefined; - // todo@API inline context object? - // @rob inline as arguments - start(context?: NotebookCellExecuteStartContext): void; + /** + * Signal that the execution has begun. + * + * @param startTime The time that execution began, in milliseconds in the Unix epoch. Used to drive the clock + * that shows for how long a cell has been running. If not given, the clock won't be shown. + */ + start(startTime?: number): void; - // todo@API inline context object? - // @rob inline as arguments - end(result?: NotebookCellExecuteEndContext): void; + /** + * Signal that execution has ended. + * + * @param success If true, a green check is shown on the cell status bar. + * If false, a red X is shown. + * If undefined, no check or X icon is shown. + * @param endTime The time that execution finished, in milliseconds in the Unix epoch. + */ + end(success: boolean | undefined, endTime?: number): void; /** * Clears the output of the cell that is executing or of another cell that is affected by this execution. @@ -12029,19 +12031,19 @@ declare module 'vscode' { * Replace all output items of existing cell output. * * @param items Output items that replace the items of existing output. - * @param output Output object or the identifier of one. + * @param output Output object that already exists. * @return A thenable that resolves when the operation finished. */ - replaceOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], output: NotebookCellOutput | string): Thenable; + replaceOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], output: NotebookCellOutput): Thenable; /** * Append output items to existing cell output. * * @param items Output items that are append to existing output. - * @param output Output object or the identifier of one. + * @param output Output object that already exists. * @return A thenable that resolves when the operation finished. */ - appendOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], output: NotebookCellOutput | string): Thenable; + appendOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], output: NotebookCellOutput): Thenable; } /** @@ -12101,11 +12103,10 @@ declare module 'vscode' { /** * Creates a new NotebookCellStatusBarItem. + * @param text The text to show for the item. + * @param alignment Whether the item is aligned to the left or right. */ - // @rob - // todo@API jsdoc for args - // todo@API should ctors only have the args for required properties? - constructor(text: string, alignment: NotebookCellStatusBarAlignment, command?: string | Command, tooltip?: string, priority?: number, accessibilityInformation?: AccessibilityInformation); + constructor(text: string, alignment: NotebookCellStatusBarAlignment); } /** @@ -12121,11 +12122,9 @@ declare module 'vscode' { * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state. * @param cell The cell for which to return items. * @param token A token triggered if this request should be cancelled. + * @return One or more {@link NotebookCellStatusBarItem cell statusbar items} */ - // @rob - //todo@API jsdoc for return-type - //todo@API should this return T | T[] - provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult; + provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult; } /** @@ -12137,74 +12136,8 @@ declare module 'vscode' { * 2. {@link NotebookController} own the execution of notebooks, e.g they create output from code cells. * 3. NotebookRenderer present notebook output in the editor. They run in a separate context. */ - // todo@api what should be in this namespace? should notebookDocuments and friends be in the workspace namespace? export namespace notebooks { - /** - * All notebook documents currently known to the editor. - */ - // todo@api move to workspace - export const notebookDocuments: readonly NotebookDocument[]; - - /** - * 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. - * - * *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. - * - * *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. - * - * @param uri The resource to open. - * @returns A promise that resolves to a {@link NotebookDocument notebook} - */ - // todo@api move to workspace - export function openNotebookDocument(uri: Uri): Thenable; - - /** - * Open an untitled notebook. The editor will prompt the user for a file - * path when the document is to be saved. - * - * @see {@link openNotebookDocument} - * @param notebookType The notebook type that should be used. - * @param content The initial contents of the notebook. - * @returns A promise that resolves to a {@link NotebookDocument notebook}. - */ - // todo@api move to workspace - export function openNotebookDocument(notebookType: string, content?: NotebookData): Thenable; - - /** - * An event that is emitted when a {@link NotebookDocument notebook} is opened. - */ - // todo@api move to workspace - export const onDidOpenNotebookDocument: Event; - - /** - * An event that is emitted when a {@link NotebookDocument notebook} is disposed. - * - * *Note 1:* There is no guarantee that this event fires when an editor tab is closed. - * - * *Note 2:* A notebook can be open but not shown in an editor which means this event can fire - * for a notebook that has not been shown in an editor. - */ - // todo@api move to workspace - export const onDidCloseNotebookDocument: Event; - - /** - * Register a {@link NotebookSerializer notebook serializer}. - * - * A notebook serializer must to be contributed through the `notebooks` extension point. When opening a notebook file, the editor will send - * the `onNotebook:` activation event, and extensions must register their serializer in return. - * - * @param notebookType A notebook. - * @param serializer A notebook serialzier. - * @param options Optional context options that define what parts of a notebook should be persisted - * @return A {@link Disposable} that unregisters this serializer when being disposed. - */ - // todo@api move to workspace - export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable; - /** * Creates a new notebook controller. * diff --git a/vscode.proposed.d.ts b/vscode.proposed.d.ts index 667119f880d..2ce6cc641a1 100644 --- a/vscode.proposed.d.ts +++ b/vscode.proposed.d.ts @@ -904,14 +904,14 @@ declare module 'vscode' { /** * The icon path or {@link ThemeIcon} for the terminal. */ - readonly iconPath?: Uri | { light: Uri; dark: Uri } | { id: string, color?: { id: string } }; + readonly iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; } export interface ExtensionTerminalOptions { /** * A themeIcon, Uri, or light and dark Uris to use as the terminal tab icon */ - readonly iconPath?: Uri | { light: Uri; dark: Uri } | { id: string, color?: { id: string } }; + readonly iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; } //#endregion @@ -1059,12 +1059,11 @@ declare module 'vscode' { //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, Notebook, deprecated + //#region https://github.com/microsoft/vscode/issues/106744, Notebook, deprecated & misc - /** - * @deprecated use notebooks instead - */ - export const notebook: typeof notebooks; + export interface NotebookCellOutput { + id: string; + } //#endregion @@ -1391,7 +1390,7 @@ declare module 'vscode' { backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, token: CancellationToken): Thenable; } - export namespace notebooks { + export namespace workspace { // TODO@api use NotebookDocumentFilter instead of just notebookType:string? // TODO@API options duplicates the more powerful variant on NotebookContentProvider @@ -1408,7 +1407,7 @@ declare module 'vscode' { exclusive?: boolean; } - export namespace notebooks { + export namespace workspace { // SPECIAL overload with NotebookRegistrationData export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions, registrationData?: NotebookRegistrationData): Disposable; // SPECIAL overload with NotebookRegistrationData @@ -2759,11 +2758,20 @@ declare module 'vscode' { //#region https://github.com/microsoft/vscode/issues/124024 @hediet @alexdima export namespace languages { + /** + * Registers an inline completion provider. + */ export function registerInlineCompletionItemProvider(selector: DocumentSelector, provider: InlineCompletionItemProvider): Disposable; } export interface InlineCompletionItemProvider { - provideInlineCompletionItems(document: TextDocument, position: Position, context: InlineCompletionContext, token: CancellationToken): ProviderResult>; + /** + * Provides inline completion items for the given position and document. + * If inline completions are enabled, this method will be called whenever the user stopped typing. + * It will also be called when the user explicitly triggers inline completions or asks for the next or previous inline completion. + * Use `context.triggerKind` to distinguish between these scenarios. + */ + provideInlineCompletionItems(document: TextDocument, position: Position, context: InlineCompletionContext, token: CancellationToken): ProviderResult | T[]>; } export interface InlineCompletionContext { @@ -2807,6 +2815,10 @@ 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, + * the whole word should be replaced with the extended word. */ range?: Range; @@ -2830,6 +2842,9 @@ declare module 'vscode' { * Be aware that this API will not ever be finalized. */ export interface InlineCompletionController { + /** + * Is fired when an inline completion item is shown to the user. + */ // eslint-disable-next-line vscode-dts-event-naming readonly onDidShowCompletionItem: Event>; } From df1a40c9827308931d7aa45b92e6c172b6d7c5de Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 14:35:49 -0700 Subject: [PATCH 03/11] notebooks => workspace rename --- src/client/common/application/notebook.ts | 11 ++++++----- .../datascience/jupyter/kernels/kernelExecution.ts | 4 ++-- src/test/vscode-mock.ts | 2 +- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/src/client/common/application/notebook.ts b/src/client/common/application/notebook.ts index 6cc67f536c6..9f7e5778531 100644 --- a/src/client/common/application/notebook.ts +++ b/src/client/common/application/notebook.ts @@ -15,7 +15,8 @@ import { NotebookEditorSelectionChangeEvent, NotebookExecuteHandler, NotebookRendererScript, - window + window, + workspace } from 'vscode'; import { UseVSCodeNotebookEditorApi } from '../constants'; import { IDisposableRegistry } from '../types'; @@ -31,7 +32,7 @@ export class VSCodeNotebook implements IVSCodeNotebook { public readonly onDidSaveNotebookDocument: Event; public readonly onDidChangeNotebookDocument: Event; public get notebookDocuments(): ReadonlyArray { - return this.canUseNotebookApi ? notebooks.notebookDocuments : []; + return this.canUseNotebookApi ? workspace.notebookDocuments : []; } public get notebookEditors() { return this.canUseNotebookApi ? window.visibleNotebookEditors : []; @@ -60,8 +61,8 @@ export class VSCodeNotebook implements IVSCodeNotebook { this.canUseNotebookApi = true; this.onDidChangeNotebookEditorSelection = window.onDidChangeNotebookEditorSelection; this.onDidChangeActiveNotebookEditor = window.onDidChangeActiveNotebookEditor; - this.onDidOpenNotebookDocument = notebooks.onDidOpenNotebookDocument; - this.onDidCloseNotebookDocument = notebooks.onDidCloseNotebookDocument; + this.onDidOpenNotebookDocument = workspace.onDidOpenNotebookDocument; + this.onDidCloseNotebookDocument = workspace.onDidCloseNotebookDocument; this.onDidChangeVisibleNotebookEditors = window.onDidChangeVisibleNotebookEditors; this.onDidSaveNotebookDocument = notebooks.onDidSaveNotebookDocument; this.onDidChangeNotebookDocument = this._onDidChangeNotebookDocument.event; @@ -86,7 +87,7 @@ export class VSCodeNotebook implements IVSCodeNotebook { transientDocumentMetadata?: { [x: string]: boolean | undefined } | undefined; } ): Disposable { - return notebooks.registerNotebookContentProvider(notebookType, provider, options); + return workspace.registerNotebookContentProvider(notebookType, provider, options); } public createNotebookController( id: string, diff --git a/src/client/datascience/jupyter/kernels/kernelExecution.ts b/src/client/datascience/jupyter/kernels/kernelExecution.ts index 26f1f70e3c0..1ac206ad2ea 100644 --- a/src/client/datascience/jupyter/kernels/kernelExecution.ts +++ b/src/client/datascience/jupyter/kernels/kernelExecution.ts @@ -3,7 +3,7 @@ 'use strict'; -import { notebooks, NotebookCell, NotebookCellKind, NotebookController, NotebookDocument } from 'vscode'; +import { NotebookCell, NotebookCellKind, NotebookController, NotebookDocument, workspace } from 'vscode'; import { ServerStatus } from '../../../../datascience-ui/interactive-common/mainState'; import { IApplicationShell } from '../../../common/application/types'; import { traceInfo, traceWarning } from '../../../common/logger'; @@ -133,7 +133,7 @@ export class KernelExecution implements IDisposable { ); // If the document is closed (user or on CI), then just stop handling the UI updates & cancel cell execution queue. - notebooks.onDidCloseNotebookDocument( + workspace.onDidCloseNotebookDocument( async (e: NotebookDocument) => { if (e === document) { if (!newCellExecutionQueue.failed || !newCellExecutionQueue.isEmpty) { diff --git a/src/test/vscode-mock.ts b/src/test/vscode-mock.ts index 3bf85bb9d77..862c125345a 100644 --- a/src/test/vscode-mock.ts +++ b/src/test/vscode-mock.ts @@ -70,7 +70,7 @@ export function initialize() { const commands = new MockCommands(); (mockedVSCode as any).commands = commands; mockedVSCodeNamespaces.commands = commands as any; - mockedVSCodeNamespaces.notebooks?.setup((nb) => nb.notebookDocuments).returns(() => []); + mockedVSCodeNamespaces.workspace?.setup((ws) => ws.notebookDocuments).returns(() => []); mockedVSCodeNamespaces.window?.setup((w) => w.visibleNotebookEditors).returns(() => []); // Use mock clipboard fo testing purposes. const clipboard = new MockClipboard(); From e0414dd6f7a573eecbd0d9e7370005d59a732fd4 Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 14:47:22 -0700 Subject: [PATCH 04/11] execution timing changes --- .../jupyter/kernels/cellExecution.ts | 23 ++++++++++--------- .../notebook/noKernelsNotebookController.ts | 2 +- src/client/datascience/utils.ts | 3 ++- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/src/client/datascience/jupyter/kernels/cellExecution.ts b/src/client/datascience/jupyter/kernels/cellExecution.ts index 494402ce634..5b3130656c4 100644 --- a/src/client/datascience/jupyter/kernels/cellExecution.ts +++ b/src/client/datascience/jupyter/kernels/cellExecution.ts @@ -185,7 +185,8 @@ export class CellExecution { `Cell Exec contents ${this.cell.document.getText().substring(0, 50)}...` ); if (!this.canExecuteCell()) { - this.execution?.end({}); + // End state is bool | undefined not optional. Undefined == not success or failure + this.execution?.end(undefined); this.execution = undefined; return; } @@ -199,7 +200,7 @@ export class CellExecution { this.startTime = new Date().getTime(); CellExecution.activeNotebookCellExecution.set(this.cell.notebook, this.execution); - this.execution?.start({ startTime: this.startTime }); + this.execution?.start(this.startTime); await Promise.all([this.initPromise, this.execution?.clearOutput()]); this.stopWatch.reset(); @@ -289,13 +290,15 @@ export class CellExecution { } private endCellTask(success: 'success' | 'failed' | 'cancelled') { if (this.isEmptyCodeCell) { - this.execution?.end({}); + // Undefined for not success or failures + this.execution?.end(undefined); } else if (success === 'success' || success === 'failed') { this.endTime = new Date().getTime(); - this.execution?.end({ endTime: this.endTime, success: success === 'success' }); + this.execution?.end(success === 'success', this.endTime); } else { // Cell was cancelled. - this.execution?.end({}); + // Undefined for not success or failures + this.execution?.end(undefined); } if (CellExecution.activeNotebookCellExecution.get(this.cell.notebook) === this.execution) { CellExecution.activeNotebookCellExecution.set(this.cell.notebook, undefined); @@ -323,7 +326,7 @@ export class CellExecution { // Create a temporary task. this.previousResultsToRestore = { ...(this.cell.executionSummary || {}) }; this.temporaryExecution = this.controller.createNotebookCellExecution(this.cell); - this.temporaryExecution?.start({}); + this.temporaryExecution?.start(); if (this.previousResultsToRestore?.executionOrder && this.execution) { this.execution.executionOrder = this.previousResultsToRestore.executionOrder; } @@ -337,12 +340,10 @@ export class CellExecution { if (this.previousResultsToRestore.executionOrder) { this.temporaryExecution.executionOrder = this.previousResultsToRestore.executionOrder; } - this.temporaryExecution.end({ - endTime: this.previousResultsToRestore.endTime, - success: this.previousResultsToRestore.success - }); + this.temporaryExecution.end(this.previousResultsToRestore.success, this.previousResultsToRestore.timing?.endTime); } else { - this.temporaryExecution?.end({}); + // Undefined for not success or failure + this.temporaryExecution?.end(undefined); } this.previousResultsToRestore = undefined; this.temporaryExecution = undefined; diff --git a/src/client/datascience/notebook/noKernelsNotebookController.ts b/src/client/datascience/notebook/noKernelsNotebookController.ts index 540fa91fc55..2bb0b6559c7 100644 --- a/src/client/datascience/notebook/noKernelsNotebookController.ts +++ b/src/client/datascience/notebook/noKernelsNotebookController.ts @@ -79,7 +79,7 @@ export class NoKernelsNotebookController implements Disposable { traceback: errorMessage.split('\n') }); task.appendOutput(errorOutput).then(noop, noop); - task.end(); + task.end(undefined); this.errorHandler.handleError(new KernelSpecNotFoundError(getNotebookMetadata(notebook))).catch(noop); } } diff --git a/src/client/datascience/utils.ts b/src/client/datascience/utils.ts index 67819ac2176..2cf95440e59 100644 --- a/src/client/datascience/utils.ts +++ b/src/client/datascience/utils.ts @@ -65,7 +65,8 @@ export function translateCellToNative( executionSummary: { executionOrder: cell.data.execution_count as number, success: true, - endTime: 0 + timing: { startTime: 0, endTime: 0 } + // endTime: 0 }, outputs: [], kind: NotebookCellKind.Code, From 623053bde45521425b1a586c71d0fb01a94ab56b Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 14:53:38 -0700 Subject: [PATCH 05/11] id and execution order --- src/client/datascience/jupyter/kernels/cellExecution.ts | 4 ++-- src/client/datascience/notebook/vscodeNotebookController.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/client/datascience/jupyter/kernels/cellExecution.ts b/src/client/datascience/jupyter/kernels/cellExecution.ts index 5b3130656c4..5e5c716c885 100644 --- a/src/client/datascience/jupyter/kernels/cellExecution.ts +++ b/src/client/datascience/jupyter/kernels/cellExecution.ts @@ -720,7 +720,7 @@ export class CellExecution { name: msg.content.name, text: formatStreamText(concatMultilineString(`${existingOutputText}${newContent}`)) }); - promise = task?.replaceOutputItems(output.items, existingOutputToAppendTo.id); + promise = task?.replaceOutputItems(output.items, existingOutputToAppendTo); } else if (clearOutput) { // Replace the current outputs with a single new output. const output = cellOutputToVSCCellOutput({ @@ -858,7 +858,7 @@ export class CellExecution { // This message could have come from a background thread. // In such circumstances, create a temporary task & use that to update the output (only cell execution tasks can update cell output). const task = this.execution || this.createTemporaryTask(); - const promise = task?.replaceOutputItems(newOutput.items, outputToBeUpdated.id); + const promise = task?.replaceOutputItems(newOutput.items, outputToBeUpdated); this.endTemporaryTask(); // await on the promise at the end, we want to minimize UI flickers. // The way we update output of other cells is to use an existing task or a temporary task. diff --git a/src/client/datascience/notebook/vscodeNotebookController.ts b/src/client/datascience/notebook/vscodeNotebookController.ts index 79a34e093e1..f8453f1042e 100644 --- a/src/client/datascience/notebook/vscodeNotebookController.ts +++ b/src/client/datascience/notebook/vscodeNotebookController.ts @@ -106,7 +106,7 @@ export class VSCodeNotebookController implements Disposable { this.controller.interruptHandler = this.handleInterrupt.bind(this); this.controller.description = getDescriptionOfKernelConnection(kernelConnection); this.controller.detail = getDetailOfKernelConnection(kernelConnection, this.pathUtils); - this.controller.hasExecutionOrder = true; + this.controller.supportsExecutionOrder = true; this.controller.supportedLanguages = this.languageService.getSupportedLanguages(kernelConnection); // Hook up to see when this NotebookController is selected by the UI this.controller.onDidChangeNotebookAssociation(this.onDidChangeNotebookAssociation, this, this.disposables); From af3716d94b93406fe149ebfa923304523eaeaf2a Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 15:29:03 -0700 Subject: [PATCH 06/11] NotebookCellData ctor change --- .../datascience/notebook/contentProvider.ts | 13 +++-- .../notebook/helpers/executionHelpers.ts | 5 +- .../datascience/notebook/helpers/helpers.ts | 28 ++++++---- .../contentProviderMain.vscode.test.ts | 55 ++++++++++++------- src/test/datascience/notebook/helper.ts | 13 ++++- .../notebook/helpers.vscode.test.ts | 26 ++++++--- 6 files changed, 88 insertions(+), 52 deletions(-) diff --git a/src/client/datascience/notebook/contentProvider.ts b/src/client/datascience/notebook/contentProvider.ts index 2606d3cca85..230f98633b7 100644 --- a/src/client/datascience/notebook/contentProvider.ts +++ b/src/client/datascience/notebook/contentProvider.ts @@ -44,15 +44,16 @@ export class NotebookContentProvider implements VSCNotebookContentProvider { if (!this.compatibilitySupport.canOpenWithVSCodeNotebookEditor(uri)) { // If not supported, return a notebook with error displayed. // We cannot, not display a notebook. - return { - cells: [ - new NotebookCellData( + const cellData = new NotebookCellData( NotebookCellKind.Markup, `# ${DataScience.usingPreviewNotebookWithOtherNotebookWarning()}`, MARKDOWN_LANGUAGE, - [], - {} - ) + ); + cellData.outputs = []; + cellData.metadata = {}; + return { + cells: [ + cellData ], metadata: {} }; diff --git a/src/client/datascience/notebook/helpers/executionHelpers.ts b/src/client/datascience/notebook/helpers/executionHelpers.ts index 081b63aa622..caa46c0b3fd 100644 --- a/src/client/datascience/notebook/helpers/executionHelpers.ts +++ b/src/client/datascience/notebook/helpers/executionHelpers.ts @@ -48,8 +48,11 @@ export async function updateCellCode(cell: NotebookCell, text: string) { export async function addNewCellAfter(cell: NotebookCell, text: string) { await chainWithPendingUpdates(cell.notebook, (edit) => { traceCellMessage(cell, 'Create new cell after current'); + const cellData = new NotebookCellData(NotebookCellKind.Code, text, cell.document.languageId) + cellData.outputs = []; + cellData.metadata = cell.metadata || {}; edit.replaceNotebookCells(cell.notebook.uri, new NotebookRange(cell.index + 1, cell.index + 1), [ - new NotebookCellData(NotebookCellKind.Code, text, cell.document.languageId, [], cell.metadata || {}) + cellData ]); }); } diff --git a/src/client/datascience/notebook/helpers/helpers.ts b/src/client/datascience/notebook/helpers/helpers.ts index 62abecbd166..fa790c27e10 100644 --- a/src/client/datascience/notebook/helpers/helpers.ts +++ b/src/client/datascience/notebook/helpers/helpers.ts @@ -304,9 +304,10 @@ function createCodeCellFromNotebookCell(cell: NotebookCell): nbformat.ICodeCell } function createNotebookCellDataFromRawCell(cell: nbformat.IRawCell): NotebookCellData { - return new NotebookCellData(NotebookCellKind.Code, concatMultilineString(cell.source), 'raw', [], { - custom: getNotebookCellMetadata(cell) - }); + const cellData = new NotebookCellData(NotebookCellKind.Code, concatMultilineString(cell.source), 'raw'); + cellData.outputs = []; + cellData.metadata = { custom: getNotebookCellMetadata(cell) }; + return cellData; } function createMarkdownCellFromNotebookCell(cell: NotebookCell): nbformat.IMarkdownCell { const cellMetadata = cell.metadata.custom as CellMetadata | undefined; @@ -321,9 +322,10 @@ function createMarkdownCellFromNotebookCell(cell: NotebookCell): nbformat.IMarkd return markdownCell; } function createNotebookCellDataFromMarkdownCell(cell: nbformat.IMarkdownCell): NotebookCellData { - return new NotebookCellData(NotebookCellKind.Markup, concatMultilineString(cell.source), MARKDOWN_LANGUAGE, [], { - custom: getNotebookCellMetadata(cell) - }); + const cellData = new NotebookCellData(NotebookCellKind.Markup, concatMultilineString(cell.source), MARKDOWN_LANGUAGE); + cellData.outputs = []; + cellData.metadata = { custom: getNotebookCellMetadata(cell) }; + return cellData; } function createNotebookCellDataFromCodeCell(cell: nbformat.ICodeCell, cellLanguage: string): NotebookCellData { // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -336,14 +338,16 @@ function createNotebookCellDataFromCodeCell(cell: nbformat.ICodeCell, cellLangua const executionSummary: NotebookCellExecutionSummary = hasExecutionCount ? { executionOrder: cell.execution_count as number } : {}; - return new NotebookCellData( + + const cellData = new NotebookCellData( NotebookCellKind.Code, source, - cellLanguage, - outputs, - { custom: getNotebookCellMetadata(cell) }, - executionSummary - ); + cellLanguage); + + cellData.outputs = outputs; + cellData.metadata = { custom: getNotebookCellMetadata(cell) }; + cellData.executionSummary = executionSummary; + return cellData; } const orderOfMimeTypes = [ 'application/vnd.*', diff --git a/src/test/datascience/notebook/contentProviderMain.vscode.test.ts b/src/test/datascience/notebook/contentProviderMain.vscode.test.ts index 79842085c50..c0328ec3c1c 100644 --- a/src/test/datascience/notebook/contentProviderMain.vscode.test.ts +++ b/src/test/datascience/notebook/contentProviderMain.vscode.test.ts @@ -69,26 +69,31 @@ suite('DataScience - VSCode Notebook ContentProvider', () => { assert.isOk(notebook); - assert.deepEqual(notebook.cells, [ - new NotebookCellData( + const codeCellData = new NotebookCellData( NotebookCellKind.Code, 'print(1)', PYTHON_LANGUAGE, - [], - { + ); + + codeCellData.outputs = []; + codeCellData.metadata = { custom: { metadata: {} } - }, - { - executionOrder: 10 - } - ), - new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE, [], { + }; + codeCellData.executionSummary = { executionOrder: 10 }; + + const markdownCellData = new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE); + markdownCellData.outputs = []; + markdownCellData.metadata = { custom: { metadata: {} } - }) + }; + + + assert.deepEqual(notebook.cells, [ + codeCellData, markdownCellData ]); }); @@ -121,26 +126,34 @@ suite('DataScience - VSCode Notebook ContentProvider', () => { assert.isOk(notebook); - assert.deepEqual(notebook.cells, [ - new NotebookCellData( + const codeCellData = new NotebookCellData( NotebookCellKind.Code, 'Console.WriteLine("1")', 'csharp', - [], - { + ); + + codeCellData.outputs = []; + codeCellData.metadata = { custom: { metadata: {} } - }, - { + }; + + codeCellData.executionSummary = { executionOrder: 10 - } - ), - new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE, [], { + }; + + const markdownCellData = new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE); + + markdownCellData.outputs = []; + markdownCellData.metadata = { custom: { metadata: {} } - }) + }; + + assert.deepEqual(notebook.cells, [ + codeCellData, markdownCellData ]); }); test('Verify mime types and order', () => { diff --git a/src/test/datascience/notebook/helper.ts b/src/test/datascience/notebook/helper.ts index 34d6ec426c3..189e2b4377b 100644 --- a/src/test/datascience/notebook/helper.ts +++ b/src/test/datascience/notebook/helper.ts @@ -87,10 +87,14 @@ export async function insertMarkdownCell(source: string, options?: { index?: num throw new Error('No active editor'); } const startNumber = options?.index ?? activeEditor.document.cellCount; - await chainWithPendingUpdates(activeEditor.document, (edit) => + await chainWithPendingUpdates(activeEditor.document, (edit) => { + const cellData = new NotebookCellData(NotebookCellKind.Markup, source, MARKDOWN_LANGUAGE); + cellData.outputs = []; + cellData.metadata = {}; edit.replaceNotebookCells(activeEditor.document.uri, new NotebookRange(startNumber, startNumber), [ - new NotebookCellData(NotebookCellKind.Markup, source, MARKDOWN_LANGUAGE, [], {}) + cellData ]) + } ); return activeEditor.document.cellAt(startNumber)!; } @@ -102,8 +106,11 @@ export async function insertCodeCell(source: string, options?: { language?: stri } const startNumber = options?.index ?? activeEditor.document.cellCount; const edit = new WorkspaceEdit(); + const cellData = new NotebookCellData(NotebookCellKind.Code, source, options?.language || PYTHON_LANGUAGE); + cellData.outputs = []; + cellData.metadata = {}; edit.replaceNotebookCells(activeEditor.document.uri, new NotebookRange(startNumber, startNumber), [ - new NotebookCellData(NotebookCellKind.Code, source, options?.language || PYTHON_LANGUAGE, [], {}) + cellData ]); await workspace.applyEdit(edit); diff --git a/src/test/datascience/notebook/helpers.vscode.test.ts b/src/test/datascience/notebook/helpers.vscode.test.ts index aacdc4af772..a9158d351cc 100644 --- a/src/test/datascience/notebook/helpers.vscode.test.ts +++ b/src/test/datascience/notebook/helpers.vscode.test.ts @@ -33,22 +33,30 @@ suite('DataScience - VSCode Notebook - helpers', () => { const notebook = notebookModelToVSCNotebookData({}, Uri.file(''), cells as any, PYTHON_LANGUAGE, {}); assert.isOk(notebook); - assert.deepEqual(notebook.cells, [ - new NotebookCellData( + + const codeCellData = new NotebookCellData( NotebookCellKind.Code, 'print(1)', PYTHON_LANGUAGE, - [], - { + ); + codeCellData.outputs = []; + codeCellData.metadata = { custom: { metadata: {} } - }, + }; + codeCellData.executionSummary = { executionOrder: 10 - } - ), - new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE, [], { + }; + const markdownCellData = new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE); + + markdownCellData.outputs = []; + markdownCellData.metadata = { custom: { metadata: {} } - }) + }; + + + assert.deepEqual(notebook.cells, [ + codeCellData, markdownCellData ]); }); suite('Outputs', () => { From d21da10889d3fa4bd02c93d57c7f38dfb94f7211 Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 15:33:14 -0700 Subject: [PATCH 07/11] view type change --- package.json | 78 ++++++++++++++++++++++++++-------------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/package.json b/package.json index 9a35db0cfe2..ff6850eb96a 100644 --- a/package.json +++ b/package.json @@ -102,7 +102,7 @@ "win": "F", "linux": "F", "key": "F", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.find" }, { @@ -110,7 +110,7 @@ "win": "K", "linux": "K", "key": "K", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "list.focusUp" }, { @@ -118,7 +118,7 @@ "win": "J", "linux": "J", "key": "J", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "list.focusDown" }, { @@ -126,7 +126,7 @@ "win": "A", "linux": "A", "key": "A", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.insertCodeCellAbove" }, { @@ -134,7 +134,7 @@ "win": "B", "linux": "B", "key": "B", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.insertCodeCellBelow" }, { @@ -142,7 +142,7 @@ "win": "D D", "linux": "D D", "key": "D D", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.delete" }, { @@ -150,7 +150,7 @@ "win": "Z", "linux": "Z", "key": "Z", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "jupyter.notebookeditor.keybind.undo" }, { @@ -158,7 +158,7 @@ "win": "S", "linux": "S", "key": "S", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "jupyter.notebookeditor.keybind.save" }, { @@ -166,7 +166,7 @@ "win": "C", "linux": "C", "key": "C", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.copy" }, { @@ -174,7 +174,7 @@ "win": "X", "linux": "X", "key": "X", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.cut" }, { @@ -182,7 +182,7 @@ "win": "V", "linux": "V", "key": "V", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.paste" }, { @@ -190,19 +190,19 @@ "win": "O", "linux": "O", "key": "O", - "when": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "jupyter.notebookeditor.keybind.toggleOutput" }, { "mac": "ctrl+shift+-", "win": "ctrl+shift+-", "linux": "ctrl+shift+-", - "when": "editorTextFocus && inputFocus && notebookEditorFocused && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "editorTextFocus && inputFocus && notebookEditorFocused && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.split" }, { "key": "ctrl+enter", - "when": "editorTextFocus && inputFocus && notebookEditorFocused && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", + "when": "editorTextFocus && inputFocus && notebookEditorFocused && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts", "command": "notebook.cell.execute" }, { @@ -297,21 +297,21 @@ "light": "resources/light/export_to_python.svg", "dark": "resources/dark/export_to_python.svg" }, - "enablement": "notebookViewType == jupyter-notebook && isWorkspaceTrusted" + "enablement": "notebookType == jupyter-notebook && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.runallcellsabove", "title": "%DataScience.runAbove%", "category": "Notebook", "icon": "$(run-above)", - "enablement": "notebookViewType == jupyter-notebook && isWorkspaceTrusted" + "enablement": "notebookType == jupyter-notebook && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.runcellandallbelow", "title": "%DataScience.runBelow%", "category": "Notebook", "icon": "$(run-below)", - "enablement": "notebookViewType == jupyter-notebook && isWorkspaceTrusted" + "enablement": "notebookType == jupyter-notebook && isWorkspaceTrusted" }, { "command": "jupyter.export", @@ -616,13 +616,13 @@ "command": "jupyter.notebookeditor.keybind.undo", "title": "%jupyter.command.jupyter.notebookeditor.keybind.undo.title%", "category": "Notebook", - "enablement": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts" + "enablement": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts" }, { "command": "jupyter.notebookeditor.keybind.save", "title": "%jupyter.command.jupyter.notebookeditor.keybind.save.title%", "category": "Notebook", - "enablement": "notebookEditorFocused && !inputFocus && notebookViewType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts" + "enablement": "notebookEditorFocused && !inputFocus && notebookType == jupyter-notebook && config.jupyter.enableKeyboardShortcuts" }, { "command": "jupyter.removeallcells", @@ -650,7 +650,7 @@ "light": "resources/light/interrupt.svg", "dark": "resources/dark/interrupt.svg" }, - "enablement": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted && jupyter.notebookeditor.canInterruptNotebookKernel" + "enablement": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted && jupyter.notebookeditor.canInterruptNotebookKernel" }, { "command": "jupyter.notebookeditor.restartkernel", @@ -764,7 +764,7 @@ "shortTitle": "%jupyter.command.jupyter.openVariableView.shorttitle%", "icon": "$(variable-group)", "category": "Jupyter", - "enablement": "notebookViewType == jupyter-notebook && !jupyter.variableViewVisible && isWorkspaceTrusted" + "enablement": "notebookType == jupyter-notebook && !jupyter.variableViewVisible && isWorkspaceTrusted" }, { "command": "jupyter.refreshDataViewer", @@ -831,31 +831,31 @@ "command": "jupyter.notebookeditor.restartkernel", "title": "%jupyter.command.jupyter.restartkernel.title%", "group": "navigation@1", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted && jupyter.notebookeditor.canrestartNotebookkernel" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted && jupyter.notebookeditor.canrestartNotebookkernel" }, { "command": "jupyter.notebookeditor.interruptkernel", "title": "%jupyter.command.jupyter.interruptkernel.title%", "group": "overflow@1", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted && jupyter.notebookeditor.canInterruptNotebookKernel" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted && jupyter.notebookeditor.canInterruptNotebookKernel" }, { "command": "jupyter.openVariableView", "title": "%jupyter.command.jupyter.openVariableView.title%", "group": "navigation@2", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.export", "title": "%DataScience.notebookExportAs%", "group": "navigation@3", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.selectNativeJupyterUriFromToolBar", "title": "%jupyter.command.jupyter.selectjupyteruri.title%", "group": "overflow@1000", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" } ], "notebook/cell/title": [ @@ -863,35 +863,35 @@ "command": "jupyter.notebookeditor.runallcellsabove", "title": "%DataScience.runAbove%", "group": "inline/cell@0", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.runcellandallbelow", "title": "%DataScience.runBelow%", "group": "inline/cell@0", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" } ], "notebook/toolbar": [ { "command": "jupyter.notebookeditor.restartkernel", "group": "navigation/execute@1", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.interruptkernel", "group": "navigation/execute@2", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.openVariableView", "group": "navigation@1", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.export", "group": "navigation@2", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" } ], "explorer/context": [ @@ -920,17 +920,17 @@ { "command": "jupyter.notebookeditor.keybind.toggleOutput", "title": "%DataScience.toggleCellOutput%", - "when": "notebookViewType == jupyter-notebook" + "when": "notebookType == jupyter-notebook" }, { "command": "jupyter.notebookeditor.runallcellsabove", "title": "%DataScience.runAbove%", - "when": "notebookEditorFocused && notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookEditorFocused && notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.runcellandallbelow", "title": "%DataScience.runBelow%", - "when": "notebookEditorFocused && notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookEditorFocused && notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.exportAsPythonScript", @@ -1187,7 +1187,7 @@ "command": "jupyter.notebookeditor.interruptkernel", "title": "%jupyter.command.jupyter.interruptkernel.title%", "category": "Notebook", - "when": "notebookViewType == 'jupyter-notebook' && isWorkspaceTrusted" + "when": "notebookType == 'jupyter-notebook' && isWorkspaceTrusted" }, { "command": "jupyter.notebookeditor.restartkernel", @@ -1205,13 +1205,13 @@ "command": "jupyter.notebookeditor.expandallcells", "title": "%jupyter.command.jupyter.expandallcells.title%", "category": "Notebook", - "when": "notebookEditorFocused && notebookViewType == 'jupyter-notebook'" + "when": "notebookEditorFocused && notebookType == 'jupyter-notebook'" }, { "command": "jupyter.notebookeditor.collapseallcells", "title": "%jupyter.command.jupyter.collapseallcells.title%", "category": "Notebook", - "when": "notebookEditorFocused && notebookViewType == 'jupyter-notebook'" + "when": "notebookEditorFocused && notebookType == 'jupyter-notebook'" }, { "command": "jupyter.notebookeditor.keybind.undo", @@ -1359,7 +1359,7 @@ "command": "jupyter.openVariableView", "title": "%jupyter.command.jupyter.openVariableView.title%", "category": "Jupyter", - "when": "notebookViewType == jupyter-notebook && isWorkspaceTrusted" + "when": "notebookType == jupyter-notebook && isWorkspaceTrusted" }, { "command": "jupyter.selectNativeJupyterUriFromToolBar", From 084b90b31d7a321ddf84ce0802ee330beb06903c Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 15:33:32 -0700 Subject: [PATCH 08/11] prettier pass --- .../jupyter/kernels/cellExecution.ts | 5 +- .../datascience/notebook/contentProvider.ts | 12 ++-- .../notebook/helpers/executionHelpers.ts | 6 +- .../datascience/notebook/helpers/helpers.ts | 13 ++-- .../contentProviderMain.vscode.test.ts | 59 ++++++++----------- src/test/datascience/notebook/helper.ts | 11 +--- .../notebook/helpers.vscode.test.ts | 28 ++++----- 7 files changed, 54 insertions(+), 80 deletions(-) diff --git a/src/client/datascience/jupyter/kernels/cellExecution.ts b/src/client/datascience/jupyter/kernels/cellExecution.ts index 5e5c716c885..f02c437e430 100644 --- a/src/client/datascience/jupyter/kernels/cellExecution.ts +++ b/src/client/datascience/jupyter/kernels/cellExecution.ts @@ -340,7 +340,10 @@ export class CellExecution { if (this.previousResultsToRestore.executionOrder) { this.temporaryExecution.executionOrder = this.previousResultsToRestore.executionOrder; } - this.temporaryExecution.end(this.previousResultsToRestore.success, this.previousResultsToRestore.timing?.endTime); + this.temporaryExecution.end( + this.previousResultsToRestore.success, + this.previousResultsToRestore.timing?.endTime + ); } else { // Undefined for not success or failure this.temporaryExecution?.end(undefined); diff --git a/src/client/datascience/notebook/contentProvider.ts b/src/client/datascience/notebook/contentProvider.ts index 230f98633b7..c39a4b521d7 100644 --- a/src/client/datascience/notebook/contentProvider.ts +++ b/src/client/datascience/notebook/contentProvider.ts @@ -45,16 +45,14 @@ export class NotebookContentProvider implements VSCNotebookContentProvider { // If not supported, return a notebook with error displayed. // We cannot, not display a notebook. const cellData = new NotebookCellData( - NotebookCellKind.Markup, - `# ${DataScience.usingPreviewNotebookWithOtherNotebookWarning()}`, - MARKDOWN_LANGUAGE, - ); + NotebookCellKind.Markup, + `# ${DataScience.usingPreviewNotebookWithOtherNotebookWarning()}`, + MARKDOWN_LANGUAGE + ); cellData.outputs = []; cellData.metadata = {}; return { - cells: [ - cellData - ], + cells: [cellData], metadata: {} }; } diff --git a/src/client/datascience/notebook/helpers/executionHelpers.ts b/src/client/datascience/notebook/helpers/executionHelpers.ts index caa46c0b3fd..590c075544d 100644 --- a/src/client/datascience/notebook/helpers/executionHelpers.ts +++ b/src/client/datascience/notebook/helpers/executionHelpers.ts @@ -48,11 +48,9 @@ export async function updateCellCode(cell: NotebookCell, text: string) { export async function addNewCellAfter(cell: NotebookCell, text: string) { await chainWithPendingUpdates(cell.notebook, (edit) => { traceCellMessage(cell, 'Create new cell after current'); - const cellData = new NotebookCellData(NotebookCellKind.Code, text, cell.document.languageId) + const cellData = new NotebookCellData(NotebookCellKind.Code, text, cell.document.languageId); cellData.outputs = []; cellData.metadata = cell.metadata || {}; - edit.replaceNotebookCells(cell.notebook.uri, new NotebookRange(cell.index + 1, cell.index + 1), [ - cellData - ]); + edit.replaceNotebookCells(cell.notebook.uri, new NotebookRange(cell.index + 1, cell.index + 1), [cellData]); }); } diff --git a/src/client/datascience/notebook/helpers/helpers.ts b/src/client/datascience/notebook/helpers/helpers.ts index fa790c27e10..d9ee63b4a47 100644 --- a/src/client/datascience/notebook/helpers/helpers.ts +++ b/src/client/datascience/notebook/helpers/helpers.ts @@ -322,7 +322,11 @@ function createMarkdownCellFromNotebookCell(cell: NotebookCell): nbformat.IMarkd return markdownCell; } function createNotebookCellDataFromMarkdownCell(cell: nbformat.IMarkdownCell): NotebookCellData { - const cellData = new NotebookCellData(NotebookCellKind.Markup, concatMultilineString(cell.source), MARKDOWN_LANGUAGE); + const cellData = new NotebookCellData( + NotebookCellKind.Markup, + concatMultilineString(cell.source), + MARKDOWN_LANGUAGE + ); cellData.outputs = []; cellData.metadata = { custom: getNotebookCellMetadata(cell) }; return cellData; @@ -338,11 +342,8 @@ function createNotebookCellDataFromCodeCell(cell: nbformat.ICodeCell, cellLangua const executionSummary: NotebookCellExecutionSummary = hasExecutionCount ? { executionOrder: cell.execution_count as number } : {}; - - const cellData = new NotebookCellData( - NotebookCellKind.Code, - source, - cellLanguage); + + const cellData = new NotebookCellData(NotebookCellKind.Code, source, cellLanguage); cellData.outputs = outputs; cellData.metadata = { custom: getNotebookCellMetadata(cell) }; diff --git a/src/test/datascience/notebook/contentProviderMain.vscode.test.ts b/src/test/datascience/notebook/contentProviderMain.vscode.test.ts index c0328ec3c1c..b5315a7fbfd 100644 --- a/src/test/datascience/notebook/contentProviderMain.vscode.test.ts +++ b/src/test/datascience/notebook/contentProviderMain.vscode.test.ts @@ -69,32 +69,25 @@ suite('DataScience - VSCode Notebook ContentProvider', () => { assert.isOk(notebook); - const codeCellData = new NotebookCellData( - NotebookCellKind.Code, - 'print(1)', - PYTHON_LANGUAGE, - ); - + const codeCellData = new NotebookCellData(NotebookCellKind.Code, 'print(1)', PYTHON_LANGUAGE); + codeCellData.outputs = []; codeCellData.metadata = { - custom: { - metadata: {} - } - }; + custom: { + metadata: {} + } + }; codeCellData.executionSummary = { executionOrder: 10 }; const markdownCellData = new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE); markdownCellData.outputs = []; markdownCellData.metadata = { - custom: { - metadata: {} - } - }; + custom: { + metadata: {} + } + }; - - assert.deepEqual(notebook.cells, [ - codeCellData, markdownCellData - ]); + assert.deepEqual(notebook.cells, [codeCellData, markdownCellData]); }); test('Return notebook with csharp language', async () => { @@ -126,35 +119,29 @@ suite('DataScience - VSCode Notebook ContentProvider', () => { assert.isOk(notebook); - const codeCellData = new NotebookCellData( - NotebookCellKind.Code, - 'Console.WriteLine("1")', - 'csharp', - ); + const codeCellData = new NotebookCellData(NotebookCellKind.Code, 'Console.WriteLine("1")', 'csharp'); codeCellData.outputs = []; codeCellData.metadata = { - custom: { - metadata: {} - } - }; + custom: { + metadata: {} + } + }; codeCellData.executionSummary = { - executionOrder: 10 - }; + executionOrder: 10 + }; const markdownCellData = new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE); markdownCellData.outputs = []; markdownCellData.metadata = { - custom: { - metadata: {} - } - }; + custom: { + metadata: {} + } + }; - assert.deepEqual(notebook.cells, [ - codeCellData, markdownCellData - ]); + assert.deepEqual(notebook.cells, [codeCellData, markdownCellData]); }); test('Verify mime types and order', () => { // https://github.com/microsoft/vscode-python/issues/11880 diff --git a/src/test/datascience/notebook/helper.ts b/src/test/datascience/notebook/helper.ts index 189e2b4377b..aa8239cced0 100644 --- a/src/test/datascience/notebook/helper.ts +++ b/src/test/datascience/notebook/helper.ts @@ -91,11 +91,8 @@ export async function insertMarkdownCell(source: string, options?: { index?: num const cellData = new NotebookCellData(NotebookCellKind.Markup, source, MARKDOWN_LANGUAGE); cellData.outputs = []; cellData.metadata = {}; - edit.replaceNotebookCells(activeEditor.document.uri, new NotebookRange(startNumber, startNumber), [ - cellData - ]) - } - ); + edit.replaceNotebookCells(activeEditor.document.uri, new NotebookRange(startNumber, startNumber), [cellData]); + }); return activeEditor.document.cellAt(startNumber)!; } export async function insertCodeCell(source: string, options?: { language?: string; index?: number }) { @@ -109,9 +106,7 @@ export async function insertCodeCell(source: string, options?: { language?: stri const cellData = new NotebookCellData(NotebookCellKind.Code, source, options?.language || PYTHON_LANGUAGE); cellData.outputs = []; cellData.metadata = {}; - edit.replaceNotebookCells(activeEditor.document.uri, new NotebookRange(startNumber, startNumber), [ - cellData - ]); + edit.replaceNotebookCells(activeEditor.document.uri, new NotebookRange(startNumber, startNumber), [cellData]); await workspace.applyEdit(edit); return activeEditor.document.cellAt(startNumber)!; diff --git a/src/test/datascience/notebook/helpers.vscode.test.ts b/src/test/datascience/notebook/helpers.vscode.test.ts index a9158d351cc..35f1b767180 100644 --- a/src/test/datascience/notebook/helpers.vscode.test.ts +++ b/src/test/datascience/notebook/helpers.vscode.test.ts @@ -34,30 +34,22 @@ suite('DataScience - VSCode Notebook - helpers', () => { assert.isOk(notebook); - const codeCellData = new NotebookCellData( - NotebookCellKind.Code, - 'print(1)', - PYTHON_LANGUAGE, - ); + const codeCellData = new NotebookCellData(NotebookCellKind.Code, 'print(1)', PYTHON_LANGUAGE); codeCellData.outputs = []; codeCellData.metadata = { - custom: { metadata: {} } - }; - codeCellData.executionSummary = - { - executionOrder: 10 - }; + custom: { metadata: {} } + }; + codeCellData.executionSummary = { + executionOrder: 10 + }; const markdownCellData = new NotebookCellData(NotebookCellKind.Markup, '# HEAD', MARKDOWN_LANGUAGE); - + markdownCellData.outputs = []; markdownCellData.metadata = { - custom: { metadata: {} } - }; - + custom: { metadata: {} } + }; - assert.deepEqual(notebook.cells, [ - codeCellData, markdownCellData - ]); + assert.deepEqual(notebook.cells, [codeCellData, markdownCellData]); }); suite('Outputs', () => { function validateCellOutputTranslation( From 598e245dade38630463b85cf115dce27b0567a58 Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 15:41:24 -0700 Subject: [PATCH 09/11] remove comment --- src/client/datascience/utils.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/client/datascience/utils.ts b/src/client/datascience/utils.ts index 2cf95440e59..e23a78bfb71 100644 --- a/src/client/datascience/utils.ts +++ b/src/client/datascience/utils.ts @@ -66,7 +66,6 @@ export function translateCellToNative( executionOrder: cell.data.execution_count as number, success: true, timing: { startTime: 0, endTime: 0 } - // endTime: 0 }, outputs: [], kind: NotebookCellKind.Code, From 0a90b003c223f7f75b227b5f1373cc75af2933c3 Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 15:44:24 -0700 Subject: [PATCH 10/11] remove comment --- src/test/mocks/mementos.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/test/mocks/mementos.ts b/src/test/mocks/mementos.ts index a398fac5f88..6e5454cfc73 100644 --- a/src/test/mocks/mementos.ts +++ b/src/test/mocks/mementos.ts @@ -25,9 +25,6 @@ export class MockMemento implements Memento { // noop. this._keys = keys; } - /** - * The stored keys. - */ public get keys(): readonly string[] { return this._keys; } From 588eda816dc5347b69d16439e2d5ce6d37a118f6 Mon Sep 17 00:00:00 2001 From: Ian Huff Date: Wed, 2 Jun 2021 16:01:29 -0700 Subject: [PATCH 11/11] review feedback --- src/client/datascience/notebook/helpers/executionHelpers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/client/datascience/notebook/helpers/executionHelpers.ts b/src/client/datascience/notebook/helpers/executionHelpers.ts index 590c075544d..c7dc7cc710c 100644 --- a/src/client/datascience/notebook/helpers/executionHelpers.ts +++ b/src/client/datascience/notebook/helpers/executionHelpers.ts @@ -50,7 +50,7 @@ export async function addNewCellAfter(cell: NotebookCell, text: string) { traceCellMessage(cell, 'Create new cell after current'); const cellData = new NotebookCellData(NotebookCellKind.Code, text, cell.document.languageId); cellData.outputs = []; - cellData.metadata = cell.metadata || {}; + cellData.metadata = {}; edit.replaceNotebookCells(cell.notebook.uri, new NotebookRange(cell.index + 1, cell.index + 1), [cellData]); }); }