@theia/plugin 1.42.1 → 1.43.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.42.1",
+  "version": "1.43.1",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.42.1"
+    "@theia/ext-scripts": "1.43.1"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "07502c238094ccd80bcdf3f74f7eec973fd7a4fc"
+  "gitHead": "df48285b7d3340e0109e89ffdb0f437ba6710378"
 }

package/src/theia.d.ts

@@ -3574,6 +3574,24 @@ export module '@theia/plugin' {
         Prepend = 3
     }
 
+    /**
+     * Options applied to the mutator.
+     */
+    export interface EnvironmentVariableMutatorOptions {
+        /**
+         * Apply to the environment just before the process is created. Defaults to true
+         */
+        applyAtProcessCreation?: boolean;
+
+        /**
+         * Apply to the environment in the shell integration script. Note that this _will not_ apply
+         * the mutator if shell integration is disabled or not working for some reason. Defaults to
+         * false.
+         * @stubbed
+         */
+        applyAtShellIntegration?: boolean;
+    }
+
     /**
      * A type of mutation and its value to be applied to an environment variable.
      */
@@ -3587,6 +3605,11 @@ export module '@theia/plugin' {
          * The value to use for the variable.
          */
         readonly value: string;
+
+        /**
+         * Options applied to the mutator.
+         */
+        readonly options: EnvironmentVariableMutatorOptions;
     }
 
     /**
@@ -3617,7 +3640,7 @@ export module '@theia/plugin' {
          * @param variable The variable to replace.
          * @param value The value to replace the variable with.
          */
-        replace(variable: string, value: string): void;
+        replace(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void;
 
         /**
          * Append a value to an environment variable.
@@ -3628,7 +3651,7 @@ export module '@theia/plugin' {
          * @param variable The variable to append to.
          * @param value The value to append to the variable.
          */
-        append(variable: string, value: string): void;
+        append(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void;
 
         /**
          * Prepend a value to an environment variable.
@@ -3639,7 +3662,7 @@ export module '@theia/plugin' {
          * @param variable The variable to prepend.
          * @param value The value to prepend to the variable.
          */
-        prepend(variable: string, value: string): void;
+        prepend(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void;
 
         /**
          * Gets the mutator that this collection applies to a variable, if any.
@@ -3669,6 +3692,39 @@ export module '@theia/plugin' {
         clear(): void;
     }
 
+    /**
+     * A collection of mutations that an extension can apply to a process environment. Applies to all scopes.
+     */
+    export interface GlobalEnvironmentVariableCollection extends EnvironmentVariableCollection {
+        /**
+         * Gets scope-specific environment variable collection for the extension. This enables alterations to
+         * terminal environment variables solely within the designated scope, and is applied in addition to (and
+         * after) the global collection.
+         *
+         * Each object obtained through this method is isolated and does not impact objects for other scopes,
+         * including the global collection.
+         *
+         * @param scope The scope to which the environment variable collection applies to.
+         *
+         * If a scope parameter is omitted, collection applicable to all relevant scopes for that parameter is
+         * returned. For instance, if the 'workspaceFolder' parameter is not specified, the collection that applies
+         * across all workspace folders will be returned.
+         *
+         * @return Environment variable collection for the passed in scope.
+         */
+        getScoped(scope: EnvironmentVariableScope): EnvironmentVariableCollection;
+    }
+
+    /**
+     * The scope object to which the environment variable collection applies.
+     */
+    export interface EnvironmentVariableScope {
+        /**
+         * Any specific workspace folder to get collection for.
+         */
+        workspaceFolder?: WorkspaceFolder;
+    }
+
     /**
      * The ExtensionMode is provided on the `ExtensionContext` and indicates the
      * mode the specific extension is running in.
@@ -3856,7 +3912,7 @@ export module '@theia/plugin' {
          * Gets the extension's environment variable collection for this workspace, enabling changes
          * to be applied to terminal environment variables.
          */
-        readonly environmentVariableCollection: EnvironmentVariableCollection;
+        readonly environmentVariableCollection: GlobalEnvironmentVariableCollection;
 
         /**
          * Get the absolute path of a resource contained in the extension.
@@ -10240,6 +10296,26 @@ export module '@theia/plugin' {
             options: FormattingOptions,
             token: CancellationToken | undefined
         ): ProviderResult<TextEdit[] | undefined>;
+
+        /**
+         * Provide formatting edits for multiple ranges in a document.
+         *
+         * This function is optional but allows a formatter to perform faster when formatting only modified ranges or when
+         * formatting a large number of selections.
+         *
+         * The given ranges are hints and providers can decide to format a smaller
+         * or larger range. Often this is done by adjusting the start and end
+         * of the range to full syntax nodes.
+         *
+         * @param document The document in which the command was invoked.
+         * @param ranges The ranges which should be formatted.
+         * @param options Options controlling formatting.
+         * @param token A cancellation token.
+         * @returns A set of text edits or a thenable that resolves to such. The lack of a result can be
+         * signaled by returning `undefined`, `null`, or an empty array.
+         * @stubbed @monaco-uplift the current monaco version does not yet use this API
+         */
+        provideDocumentRangesFormattingEdits?(document: TextDocument, ranges: Range[], options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>;
     }
 
     /**
@@ -15733,6 +15809,8 @@ export module '@theia/plugin' {
         export function registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable;
     }
 
+    // based on VS Code API 1.81.0
+
     /**
      * Namespace for testing functionality. Tests are published by registering
      * {@link TestController} instances, then adding {@link TestItem TestItems}.
@@ -15746,7 +15824,6 @@ export module '@theia/plugin' {
          * @param id Identifier for the controller, must be globally unique.
          * @param label A human-readable label for the controller.
          * @returns An instance of the {@link TestController}.
-         * @stubbed
          */
         export function createTestController(id: string, label: string): TestController;
     }
@@ -15791,14 +15868,12 @@ export module '@theia/plugin' {
          * normally and the user requests to re-run them in debug mode, the editor
          * will attempt use a configuration with the same label of the `Debug`
          * kind. If there is no such configuration, the default will be used.
-         * @stubbed
          */
         label: string;
 
         /**
          * Configures what kind of execution this profile controls. If there
          * are no profiles for a kind, it will not be available in the UI.
-         * @stubbed
          */
         readonly kind: TestRunProfileKind;
 
@@ -15808,7 +15883,6 @@ export module '@theia/plugin' {
          * the generic "run all" button, then the default profile for
          * {@link TestRunProfileKind.Run} will be executed, although the
          * user can configure this.
-         * @stubbed
          */
         isDefault: boolean;
 
@@ -15816,14 +15890,12 @@ export module '@theia/plugin' {
          * Whether this profile supports continuous running of requests. If so,
          * then {@link TestRunRequest.continuous} may be set to `true`. Defaults
          * to false.
-         * @stubbed
          */
         supportsContinuousRun: boolean;
 
         /**
          * Associated tag for the profile. If this is set, only {@link TestItem}
          * instances with the same tag will be eligible to execute in this profile.
-         * @stubbed
          */
         tag: TestTag | undefined;
 
@@ -15832,7 +15904,6 @@ export module '@theia/plugin' {
          * UI, and this method will be invoked when it's clicked. When called,
          * you can take other editor actions, such as showing a quick pick or
          * opening a configuration file.
-         * @stubbed
          */
         configureHandler: (() => void) | undefined;
 
@@ -15852,13 +15923,11 @@ export module '@theia/plugin' {
          * test run. If cancellation is requested on this token, all {@link TestRun}
          * instances associated with the request will be
          * automatically cancelled as well.
-         * @stubbed
          */
         runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable<void> | void;
 
         /**
          * Deletes the run profile.
-         * @stubbed
          */
         dispose(): void;
     }
@@ -15871,15 +15940,13 @@ export module '@theia/plugin' {
      */
     export interface TestController {
         /**
-         * The id of the controller passed in {@link vscode.tests.createTestController}.
+         * The id of the controller passed in {@link tests.createTestController}.
          * This must be globally unique.
-         * @stubbed
          */
         readonly id: string;
 
         /**
          * Human-readable label for the test controller.
-         * @stubbed
          */
         label: string;
 
@@ -15889,12 +15956,11 @@ export module '@theia/plugin' {
          * "test tree."
          *
          * The extension controls when to add tests. For example, extensions should
-         * add tests for a file when {@link vscode.workspace.onDidOpenTextDocument}
+         * add tests for a file when {@link workspace.onDidOpenTextDocument}
          * fires in order for decorations for tests within a file to be visible.
          *
          * However, the editor may sometimes explicitly request children using the
          * {@link resolveHandler} See the documentation on that method for more details.
-         * @stubbed
          */
         readonly items: TestItemCollection;
 
@@ -15909,7 +15975,6 @@ export module '@theia/plugin' {
          * @param supportsContinuousRun Whether the profile supports continuous running.
          * @returns An instance of a {@link TestRunProfile}, which is automatically
          * associated with this controller.
-         * @stubbed
          */
         createRunProfile(label: string, kind: TestRunProfileKind, runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable<void> | void, isDefault?: boolean, tag?: TestTag, supportsContinuousRun?: boolean): TestRunProfile;
 
@@ -15917,7 +15982,7 @@ export module '@theia/plugin' {
          * A function provided by the extension that the editor may call to request
          * children of a test item, if the {@link TestItem.canResolveChildren} is
          * `true`. When called, the item should discover children and call
-         * {@link vscode.tests.createTestItem} as children are discovered.
+         * {@link TestController.createTestItem} as children are discovered.
          *
          * Generally the extension manages the lifecycle of test items, but under
          * certain conditions the editor may request the children of a specific
@@ -15930,7 +15995,6 @@ export module '@theia/plugin' {
          *
          * @param item An unresolved test item for which children are being
          * requested, or `undefined` to resolve the controller's initial {@link TestController.items items}.
-         * @stubbed
          */
         resolveHandler?: (item: TestItem | undefined) => Thenable<void> | void;
 
@@ -15944,7 +16008,6 @@ export module '@theia/plugin' {
          * a {@link FileSystemWatcher} for example, and use this method as a fallback.
          *
          * @returns A thenable that resolves when tests have been refreshed.
-         * @stubbed
          */
         refreshHandler: ((token: CancellationToken) => Thenable<void> | void) | undefined;
 
@@ -15968,7 +16031,6 @@ export module '@theia/plugin' {
          * a file already saved externally, such as a coverage information file.
          * @returns An instance of the {@link TestRun}. It will be considered "running"
          * from the moment this method is invoked until {@link TestRun.end} is called.
-         * @stubbed
          */
         createTestRun(request: TestRunRequest, name?: string, persist?: boolean): TestRun;
 
@@ -15981,7 +16043,6 @@ export module '@theia/plugin' {
          * in the {@link TestItemCollection} it's added to.
          * @param label Human-readable label of the test item.
          * @param uri URI this TestItem is associated with. May be a file or directory.
-         * @stubbed
          */
         createTestItem(id: string, label: string, uri?: Uri): TestItem;
 
@@ -16000,23 +16061,21 @@ export module '@theia/plugin' {
          * in the editor's UI.
          *
          * @param item Item to mark as outdated. If undefined, all the controller's items are marked outdated.
-         * @stubbed
          */
         invalidateTestResults(items?: TestItem | readonly TestItem[]): void;
 
         /**
          * Unregisters the test controller, disposing of its associated tests
          * and unpersisted results.
-         * @stubbed
          */
         dispose(): void;
     }
 
     /**
      * A TestRunRequest is a precursor to a {@link TestRun}, which in turn is
-     * created by passing a request to {@link tests.runTests}. The TestRunRequest
-     * contains information about which tests should be run, which should not be
-     * run, and how they are run (via the {@link TestRunRequest.profile profile}).
+     * created by passing a request to {@link TestController.createTestRun}. The
+     * TestRunRequest contains information about which tests should be run, which
+     * should not be run, and how they are run (via the {@link TestRunRequest.profile profile}).
      *
      * In general, TestRunRequests are created by the editor and pass to
      * {@link TestRunProfile.runHandler}, however you can also create test
@@ -16066,48 +16125,43 @@ export module '@theia/plugin' {
     }
 
     /**
-     * Options given to {@link TestController.runTests}
+     * A TestRun represents an in-progress or completed test run and
+     * provides methods to report the state of individual tests in the run.
      */
     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.
-         * @stubbed
          */
         readonly name: string | undefined;
 
         /**
          * A cancellation token which will be triggered when the test run is
          * canceled from the UI.
-         * @stubbed
          */
         readonly token: CancellationToken;
 
         /**
          * Whether the test run will be persisted across reloads by the editor.
-         * @stubbed
          */
         readonly isPersisted: boolean;
 
         /**
          * Indicates a test is queued for later execution.
          * @param test Test item to update.
-         * @stubbed
          */
         enqueued(test: TestItem): void;
 
         /**
          * Indicates a test has started running.
          * @param test Test item to update.
-         * @stubbed
          */
         started(test: TestItem): void;
 
         /**
          * Indicates a test has been skipped.
          * @param test Test item to update.
-         * @stubbed
          */
         skipped(test: TestItem): void;
 
@@ -16117,7 +16171,6 @@ export module '@theia/plugin' {
          * @param test Test item to update.
          * @param message Messages associated with the test failure.
          * @param duration How long the test took to execute, in milliseconds.
-         * @stubbed
          */
         failed(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void;
 
@@ -16129,7 +16182,6 @@ export module '@theia/plugin' {
          * @param test Test item to update.
          * @param message Messages associated with the test failure.
          * @param duration How long the test took to execute, in milliseconds.
-         * @stubbed
          */
         errored(test: TestItem, message: TestMessage | readonly TestMessage[], duration?: number): void;
 
@@ -16137,27 +16189,25 @@ export module '@theia/plugin' {
          * Indicates a test has passed.
          * @param test Test item to update.
          * @param duration How long the test took to execute, in milliseconds.
-         * @stubbed
          */
         passed(test: TestItem, duration?: number): void;
 
         /**
          * Appends raw output from the test runner. On the user's request, the
          * output will be displayed in a terminal. ANSI escape sequences,
-         * such as colors and text styles, are supported.
+         * such as colors and text styles, are supported. New lines must be given
+         * as CRLF (`\r\n`) rather than LF (`\n`).
          *
          * @param output Output text to append.
          * @param location Indicate that the output was logged at the given
          * location.
          * @param test Test item to associate the output with.
-         * @stubbed
          */
         appendOutput(output: string, location?: Location, test?: TestItem): void;
 
         /**
-         * Signals that the end of the test run. Any tests included in the run whose
+         * Signals the end of the test run. Any tests included in the run whose
          * states have not been updated will have their state reset.
-         * @stubbed
          */
         end(): void;
     }
@@ -16169,14 +16219,12 @@ export module '@theia/plugin' {
     export interface TestItemCollection extends Iterable<[id: string, testItem: TestItem]> {
         /**
          * Gets the number of items in the collection.
-         * @stubbed
          */
         readonly size: number;
 
         /**
          * Replaces the items stored by the collection.
          * @param items Items to store.
-         * @stubbed
          */
         replace(items: readonly TestItem[]): void;
 
@@ -16185,7 +16233,6 @@ export module '@theia/plugin' {
          *
          * @param callback Function to execute for each entry.
          * @param thisArg The `this` context used when invoking the handler function.
-         * @stubbed
          */
         forEach(callback: (item: TestItem, collection: TestItemCollection) => unknown, thisArg?: any): void;
 
@@ -16193,14 +16240,12 @@ export module '@theia/plugin' {
          * Adds the test item to the children. If an item with the same ID already
          * exists, it'll be replaced.
          * @param item Item to add.
-         * @stubbed
          */
         add(item: TestItem): void;
 
         /**
          * Removes a single test item from the collection.
          * @param itemId Item ID to delete.
-         * @stubbed
          */
         delete(itemId: string): void;
 
@@ -16208,7 +16253,6 @@ export module '@theia/plugin' {
          * Efficiently gets a test item by ID, if it exists, in the children.
          * @param itemId Item ID to get.
          * @returns The found item or undefined if it does not exist.
-         * @stubbed
          */
         get(itemId: string): TestItem | undefined;
     }
@@ -16225,20 +16269,17 @@ export module '@theia/plugin' {
          * test results and tests in the document with those in the workspace
          * (test explorer). This cannot change for the lifetime of the `TestItem`,
          * and must be unique among its parent's direct children.
-         * @stubbed
          */
         readonly id: string;
 
         /**
          * URI this `TestItem` is associated with. May be a file or directory.
-         * @stubbed
          */
         readonly uri: Uri | undefined;
 
         /**
          * The children of this test item. For a test suite, this may contain the
          * individual test cases or nested suites.
-         * @stubbed
          */
         readonly children: TestItemCollection;
 
@@ -16246,14 +16287,12 @@ export module '@theia/plugin' {
          * The parent of this item. It's set automatically, and is undefined
          * top-level items in the {@link TestController.items} and for items that
          * aren't yet included in another item's {@link TestItem.children children}.
-         * @stubbed
          */
         readonly parent: TestItem | undefined;
 
         /**
          * Tags associated with this test item. May be used in combination with
-         * {@link TestRunProfile.tags}, or simply as an organizational feature.
-         * @stubbed
+         * {@link TestRunProfile.tag tags}, or simply as an organizational feature.
          */
         tags: readonly TestTag[];
 
@@ -16265,7 +16304,6 @@ export module '@theia/plugin' {
          * to be invoked with the item.
          *
          * Default to `false`.
-         * @stubbed
          */
         canResolveChildren: boolean;
 
@@ -16274,19 +16312,16 @@ export module '@theia/plugin' {
          * This is useful for showing status while discovering children.
          *
          * Defaults to `false`.
-         * @stubbed
          */
         busy: boolean;
 
         /**
          * Display name describing the test case.
-         * @stubbed
          */
         label: string;
 
         /**
          * Optional description that appears next to the label.
-         * @stubbed
          */
         description?: string;
 
@@ -16294,7 +16329,6 @@ export module '@theia/plugin' {
          * A string that should be used when comparing this item
          * with other items. When `falsy` the {@link TestItem.label label}
          * is used.
-         * @stubbed
          */
         sortText?: string | undefined;
 
@@ -16302,7 +16336,6 @@ export module '@theia/plugin' {
          * Location of the test item in its {@link TestItem.uri uri}.
          *
          * This is only meaningful if the `uri` points to a file.
-         * @stubbed
          */
         range: Range | undefined;
 
@@ -16311,7 +16344,6 @@ export module '@theia/plugin' {
          *
          * Note that this is not a test result and should only be used to represent errors in
          * test discovery, such as syntax errors.
-         * @stubbed
          */
         error: string | MarkdownString | undefined;
     }
@@ -16355,7 +16387,6 @@ export module '@theia/plugin' {
          */
         constructor(message: string | MarkdownString);
     }
-
     /**
      * Thenable is a common denominator between ES6 promises, Q, jquery.Deferred, WinJS.Promise,
      * and others. This API makes no assumption about what promise library is being used which
@@ -16372,5 +16403,4 @@ export module '@theia/plugin' {
         then<TResult>(onfulfilled?: (value: T) => TResult | Thenable<TResult>, onrejected?: (reason: any) => TResult | Thenable<TResult>): Thenable<TResult>;
         then<TResult>(onfulfilled?: (value: T) => TResult | Thenable<TResult>, onrejected?: (reason: any) => void): Thenable<TResult>;
     }
-
 }

package/src/theia.proposed.documentPaste.d.ts

@@ -59,24 +59,18 @@ export module '@theia/plugin' {
      * An operation applied on paste
      */
     class DocumentPasteEdit {
-        /**
-         * Identifies the type of edit.
-         *
-         * This id should be unique within the extension but does not need to be unique across extensions.
-         */
-        id: string;
-
         /**
          * Human readable label that describes the edit.
          */
         label: string;
 
         /**
-         * The relative priority of this edit. Higher priority items are shown first in the UI.
-         *
-         * Defaults to `0`.
+         * Controls the ordering or multiple paste edits. If this provider yield to edits, it will be shown lower in the list.
          */
-        priority?: number;
+        yieldTo?: ReadonlyArray<
+            | { readonly extensionId: string; readonly providerId: string }
+            | { readonly mimeType: string }
+        >;
 
         /**
          * The text or snippet to insert at the pasted locations.
@@ -97,6 +91,15 @@ export module '@theia/plugin' {
     }
 
     interface DocumentPasteProviderMetadata {
+        /**
+         * Identifies the provider.
+         *
+         * This id is used when users configure the default provider for paste.
+         *
+         * This id should be unique within the extension but does not need to be unique across extensions.
+         */
+        readonly id: string;
+
         /**
          * Mime types that {@link DocumentPasteEditProvider.prepareDocumentPaste provideDocumentPasteEdits} may add on copy.
          */

package/src/theia.proposed.dropMetadata.d.ts

@@ -25,27 +25,36 @@ export module '@theia/plugin' {
     // https://github.com/microsoft/vscode/issues/179430
 
     export interface DocumentDropEdit {
+
         /**
-         * Identifies the type of edit.
-         *
-         * This id should be unique within the extension but does not need to be unique across extensions.
+         * Human readable label that describes the edit.
          */
-        id?: string;
+        label?: string;
 
         /**
-         * The relative priority of this edit. Higher priority items are shown first in the UI.
-         *
-         * Defaults to `0`.
+         * The mime type from the {@link DataTransfer} that this edit applies.
          */
-        priority?: number;
+        handledMimeType?: string;
 
         /**
-         * Human readable label that describes the edit.
+         * Controls the ordering or multiple paste edits. If this provider yield to edits, it will be shown lower in the list.
          */
-        label?: string;
+        yieldTo?: ReadonlyArray<
+            | { readonly extensionId: string; readonly providerId: string }
+            | { readonly mimeType: string }
+        >;
     }
 
     export interface DocumentDropEditProviderMetadata {
+        /**
+         * Identifies the provider.
+         *
+         * This id is used when users configure the default provider for drop.
+         *
+         * This id should be unique within the extension but does not need to be unique across extensions.
+         */
+        readonly id: string;
+
         /**
          * List of data transfer types that the provider supports.
          *

package/src/theia.proposed.terminalQuickFixProvider.d.ts

@@ -22,6 +22,8 @@
 
 export module '@theia/plugin' {
 
+    export type SingleOrMany<T> = T[] | T;
+
     export namespace window {
         /**
          * @param provider A terminal quick fix provider
@@ -37,7 +39,8 @@ export module '@theia/plugin' {
          * @param token A cancellation token indicating the result is no longer needed
          * @return Terminal quick fix(es) if any
          */
-        provideTerminalQuickFixes(commandMatchResult: TerminalCommandMatchResult, token: CancellationToken): TerminalQuickFix[] | TerminalQuickFix | undefined;
+        provideTerminalQuickFixes(commandMatchResult: TerminalCommandMatchResult, token: CancellationToken):
+            ProviderResult<SingleOrMany<TerminalQuickFixExecuteTerminalCommand | TerminalQuickFixOpener | Command>>;
     }
 
     export interface TerminalCommandMatchResult {
@@ -49,13 +52,19 @@ export module '@theia/plugin' {
         };
     }
 
-    interface TerminalQuickFix {
-        type: TerminalQuickFixType;
+    export class TerminalQuickFixExecuteTerminalCommand {
+        /**
+         * The terminal command to run
+         */
+        terminalCommand: string;
+        constructor(terminalCommand: string);
     }
-
-    enum TerminalQuickFixType {
-        command = 'command',
-        opener = 'opener'
+    export class TerminalQuickFixOpener {
+        /**
+         * The uri to open
+         */
+        uri: Uri;
+        constructor(uri: Uri);
     }
 
     /**