@theia/plugin 1.48.2 → 1.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.48.2",
+  "version": "1.49.0",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.48.2"
+    "@theia/ext-scripts": "1.49.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "0e9583d043dde303de7a0f86f68439659f8827b0"
+  "gitHead": "d413dadd87a70fce1c80df7eb22d9d2529cc129f"
 }

package/src/theia.d.ts

@@ -16035,6 +16035,18 @@ export module '@theia/plugin' {
          */
         runHandler: (request: TestRunRequest, token: CancellationToken) => Thenable<void> | void;
 
+        /**
+         * An extension-provided function that provides detailed statement and
+         * function-level coverage for a file. The editor will call this when more
+         * detail is needed for a file, such as when it's opened in an editor or
+         * expanded in the **Test Coverage** view.
+         *
+         * The {@link FileCoverage} object passed to this function is the same instance
+         * emitted on {@link TestRun.addCoverage} calls associated with this profile.
+         * @stubbed
+         */
+        loadDetailedCoverage?: (testRun: TestRun, fileCoverage: FileCoverage, token: CancellationToken) => Thenable<FileCoverageDetail[]>;
+
         /**
          * Deletes the run profile.
          */
@@ -16314,11 +16326,23 @@ export module '@theia/plugin' {
          */
         appendOutput(output: string, location?: Location, test?: TestItem): void;
 
+        /**
+         * Adds coverage for a file in the run.
+         * @stubbed
+         */
+        addCoverage(fileCoverage: FileCoverage): void;
+
         /**
          * Signals the end of the test run. Any tests included in the run whose
          * states have not been updated will have their state reset.
          */
         end(): void;
+
+        /**
+         * An event fired when the editor is no longer interested in data
+         * associated with the test run.
+         */
+        onDidDispose: Event<void>;
     }
 
     /**
@@ -16527,6 +16551,178 @@ export module '@theia/plugin' {
          */
         constructor(message: string | MarkdownString);
     }
+
+    /**
+     * A class that contains information about a covered resource. A count can
+     * be give for lines, branches, and declarations in a file.
+     */
+    export class TestCoverageCount {
+        /**
+         * Number of items covered in the file.
+         */
+        covered: number;
+        /**
+         * Total number of covered items in the file.
+         */
+        total: number;
+
+        /**
+         * @param covered Value for {@link TestCoverageCount.covered}
+         * @param total Value for {@link TestCoverageCount.total}
+         */
+        constructor(covered: number, total: number);
+    }
+
+    /**
+     * Contains coverage metadata for a file.
+     */
+    export class FileCoverage {
+        /**
+         * File URI.
+         */
+        readonly uri: Uri;
+
+        /**
+         * Statement coverage information. If the reporter does not provide statement
+         * coverage information, this can instead be used to represent line coverage.
+         */
+        statementCoverage: TestCoverageCount;
+
+        /**
+         * Branch coverage information.
+         */
+        branchCoverage?: TestCoverageCount;
+
+        /**
+         * Declaration coverage information. Depending on the reporter and
+         * language, this may be types such as functions, methods, or namespaces.
+         */
+        declarationCoverage?: TestCoverageCount;
+
+        /**
+         * Creates a {@link FileCoverage} instance with counts filled in from
+         * the coverage details.
+         * @param uri Covered file URI
+         * @param detailed Detailed coverage information
+         */
+        static fromDetails(uri: Uri, details: readonly FileCoverageDetail[]): FileCoverage;
+
+        /**
+         * @param uri Covered file URI
+         * @param statementCoverage Statement coverage information. If the reporter
+         * does not provide statement coverage information, this can instead be
+         * used to represent line coverage.
+         * @param branchCoverage Branch coverage information
+         * @param declarationCoverage Declaration coverage information
+         */
+        constructor(
+            uri: Uri,
+            statementCoverage: TestCoverageCount,
+            branchCoverage?: TestCoverageCount,
+            declarationCoverage?: TestCoverageCount,
+        );
+    }
+
+    /**
+     * Contains coverage information for a single statement or line.
+     */
+    export class StatementCoverage {
+        /**
+         * The number of times this statement was executed, or a boolean indicating
+         * whether it was executed if the exact count is unknown. If zero or false,
+         * the statement will be marked as un-covered.
+         */
+        executed: number | boolean;
+
+        /**
+         * Statement location.
+         */
+        location: Position | Range;
+
+        /**
+         * Coverage from branches of this line or statement. If it's not a
+         * conditional, this will be empty.
+         */
+        branches: BranchCoverage[];
+
+        /**
+         * @param location The statement position.
+         * @param executed The number of times this statement was executed, or a
+         * boolean indicating  whether it was executed if the exact count is
+         * unknown. If zero or false, the statement will be marked as un-covered.
+         * @param branches Coverage from branches of this line.  If it's not a
+         * conditional, this should be omitted.
+         */
+        constructor(executed: number | boolean, location: Position | Range, branches?: BranchCoverage[]);
+    }
+
+    /**
+     * Contains coverage information for a branch of a {@link StatementCoverage}.
+     */
+    export class BranchCoverage {
+        /**
+         * The number of times this branch was executed, or a boolean indicating
+         * whether it was executed if the exact count is unknown. If zero or false,
+         * the branch will be marked as un-covered.
+         */
+        executed: number | boolean;
+
+        /**
+         * Branch location.
+         */
+        location?: Position | Range;
+
+        /**
+         * Label for the branch, used in the context of "the ${label} branch was
+         * not taken," for example.
+         */
+        label?: string;
+
+        /**
+         * @param executed The number of times this branch was executed, or a
+         * boolean indicating  whether it was executed if the exact count is
+         * unknown. If zero or false, the branch will be marked as un-covered.
+         * @param location The branch position.
+         */
+        constructor(executed: number | boolean, location?: Position | Range, label?: string);
+    }
+
+    /**
+     * Contains coverage information for a declaration. Depending on the reporter
+     * and language, this may be types such as functions, methods, or namespaces.
+     */
+    export class DeclarationCoverage {
+        /**
+         * Name of the declaration.
+         */
+        name: string;
+
+        /**
+         * The number of times this declaration was executed, or a boolean
+         * indicating whether it was executed if the exact count is unknown. If
+         * zero or false, the declaration will be marked as un-covered.
+         */
+        executed: number | boolean;
+
+        /**
+         * Declaration location.
+         */
+        location: Position | Range;
+
+        /**
+         * @param executed The number of times this declaration was executed, or a
+         * boolean indicating  whether it was executed if the exact count is
+         * unknown. If zero or false, the declaration will be marked as un-covered.
+         * @param location The declaration position.
+         */
+        constructor(name: string, executed: number | boolean, location: Position | Range);
+    }
+
+    /**
+     * Coverage details returned from {@link TestRunProfile.loadDetailedCoverage}.
+     */
+    export type FileCoverageDetail = StatementCoverage | DeclarationCoverage;
+
     /**
      * 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

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

@@ -23,54 +23,107 @@
 export module '@theia/plugin' {
 
     /**
-     * Provider invoked when the user copies and pastes code.
+     * The reason why paste edits were requested.
      */
-    export interface DocumentPasteEditProvider {
+    export enum DocumentPasteTriggerKind {
+        /**
+         * Pasting was requested as part of a normal paste operation.
+         */
+        Automatic = 0,
+
+        /**
+         * Pasting was requested by the user with the `paste as` command.
+         */
+        PasteAs = 1,
+    }
+
+    /**
+     * Additional information about the paste operation.
+     */
+
+    export interface DocumentPasteEditContext {
+        /**
+         * Requested kind of paste edits to return.
+         */
+        readonly only: DocumentPasteEditKind | undefined;
+
+        /**
+         * The reason why paste edits were requested.
+         */
+        readonly triggerKind: DocumentPasteTriggerKind;
+    }
+
+    /**
+     * Provider invoked when the user copies or pastes in a {@linkcode TextDocument}.
+     */
+    interface DocumentPasteEditProvider<T extends DocumentPasteEdit = DocumentPasteEdit> {
 
         /**
          * Optional method invoked after the user copies text in a file.
          *
-         * During {@link prepareDocumentPaste}, an extension can compute metadata that is attached to
-         * a {@link DataTransfer} and is passed back to the provider in {@link provideDocumentPasteEdits}.
+         * This allows the provider to attach copy metadata to the {@link DataTransfer}
+         * which is then passed back to providers in {@linkcode provideDocumentPasteEdits}.
+         *
+         * Note that currently any changes to the {@linkcode DataTransfer} are isolated to the current editor session.
+         * This means that added metadata cannot be seen by other applications.
          *
          * @param document Document where the copy took place.
-         * @param ranges Ranges being copied in the `document`.
-         * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for later use in  {@link provideDocumentPasteEdits}.
+         * @param ranges Ranges being copied in {@linkcode document}.
+         * @param dataTransfer The data transfer associated with the copy. You can store additional values on this for later use in  {@linkcode provideDocumentPasteEdits}.
+         * This object is only valid for the duration of this method.
          * @param token A cancellation token.
+         *
+         * @return Optional thenable that resolves when all changes to the `dataTransfer` are complete.
          */
         prepareDocumentPaste?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): void | Thenable<void>;
 
         /**
          * Invoked before the user pastes into a document.
          *
-         * In this method, extensions can return a workspace edit that replaces the standard pasting behavior.
+         * Returned edits can replace the standard pasting behavior.
          *
          * @param document Document being pasted into
-         * @param ranges Currently selected ranges in the document.
-         * @param dataTransfer The data transfer associated with the paste.
+         * @param ranges Range in the {@linkcode document} to paste into.
+         * @param dataTransfer The {@link DataTransfer data transfer} associated with the paste. This object is only valid for the duration of the paste operation.
+         * @param context Additional context for the paste.
          * @param token A cancellation token.
          *
-         * @return Optional workspace edit that applies the paste. Return undefined to use standard pasting.
+         * @return Set of potential {@link DocumentPasteEdit edits} that apply the paste. Return `undefined` to use standard pasting.
          */
-        provideDocumentPasteEdits?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<DocumentPasteEdit>;
+        provideDocumentPasteEdits?(document: TextDocument, ranges: readonly Range[], dataTransfer: DataTransfer, context: DocumentPasteEditContext,
+            token: CancellationToken): ProviderResult<T[]>;
+
+        /**
+         * Optional method which fills in the {@linkcode DocumentPasteEdit.additionalEdit} before the edit is applied.
+         *
+         * This is called once per edit and should be used if generating the complete edit may take a long time.
+         * Resolve can only be used to change {@link DocumentPasteEdit.additionalEdit}.
+         *
+         * @param pasteEdit The {@linkcode DocumentPasteEdit} to resolve.
+         * @param token A cancellation token.
+         *
+         * @returns The resolved paste edit or a thenable that resolves to such. It is OK to return the given
+         * `pasteEdit`. If no result is returned, the given `pasteEdit` is used.
+         */
+        resolveDocumentPasteEdit?(pasteEdit: T, token: CancellationToken): ProviderResult<T>;
     }
 
     /**
-     * An operation applied on paste
+     * An edit applied on paste.
      */
     class DocumentPasteEdit {
+
         /**
          * Human readable label that describes the edit.
          */
-        label: string;
+        title: string;
 
         /**
-         * Controls the ordering or multiple paste edits. If this provider yield to edits, it will be shown lower in the list.
+         * {@link DocumentPasteEditKind Kind} of the edit.
+         *
+         * Used to identify specific types of edits.
          */
-        yieldTo?: ReadonlyArray<
-            | { readonly extensionId: string; readonly providerId: string }
-            | { readonly mimeType: string }
-        >;
+        kind: DocumentPasteEditKind;
 
         /**
          * The text or snippet to insert at the pasted locations.
@@ -83,43 +136,77 @@ export module '@theia/plugin' {
         additionalEdit?: WorkspaceEdit;
 
         /**
-         * @param insertText The text or snippet to insert at the pasted locations.
+         * Controls the ordering of paste edits provided by multiple providers.
          *
-         * TODO: Reverse args, but this will break existing consumers :(
+         * If this edit yields to another, it will be shown lower in the list of paste edit.
          */
-        constructor(insertText: string | SnippetString, id: string, label: string);
+        yieldTo?: readonly DocumentPasteEditKind[];
+
+        /**
+         * Create a new paste edit.
+         *
+         * @param insertText The text or snippet to insert at the pasted locations.
+         * @param title Human readable label that describes the edit.
+         * @param kind {@link DocumentPasteEditKind Kind} of the edit.
+         */
+        constructor(insertText: string | SnippetString, title: string, kind: DocumentPasteEditKind);
+    }
+
+    /**
+     * TODO: Share with code action kind?
+     */
+    class DocumentPasteEditKind {
+        static readonly Empty: DocumentPasteEditKind;
+
+        // TODO: Add `Text` any others?
+
+        private constructor(value: string);
+
+        readonly value: string;
+
+        append(...parts: string[]): CodeActionKind;
+        intersects(other: CodeActionKind): boolean;
+        contains(other: CodeActionKind): boolean;
     }
 
     interface DocumentPasteProviderMetadata {
         /**
-         * Identifies the provider.
-         *
-         * This id is used when users configure the default provider for paste.
+         * List of {@link DocumentPasteEditKind kinds} that the provider may return in {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits}.
          *
-         * This id should be unique within the extension but does not need to be unique across extensions.
+         * The provider will only be invoked when one of these kinds is being requested. For normal pasting, all providers will be invoked.
          */
-        readonly id: string;
+        readonly providedPasteEditKinds: readonly DocumentPasteEditKind[];
 
         /**
-         * Mime types that {@link DocumentPasteEditProvider.prepareDocumentPaste provideDocumentPasteEdits} may add on copy.
+         * Mime types that {@linkcode DocumentPasteEditProvider.prepareDocumentPaste prepareDocumentPaste} may add on copy.
          */
         readonly copyMimeTypes?: readonly string[];
 
         /**
-         * Mime types that {@link DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits} should be invoked for.
+         * Mime types that {@linkcode DocumentPasteEditProvider.provideDocumentPasteEdits provideDocumentPasteEdits} should be invoked for.
          *
          * This can either be an exact mime type such as `image/png`, or a wildcard pattern such as `image/*`.
          *
          * Use `text/uri-list` for resources dropped from the explorer or other tree views in the workbench.
          *
-         * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@link DataTransfer}.
-         * Note that {@link DataTransferFile} entries are only created when dropping content from outside the editor, such as
+         * Use `files` to indicate that the provider should be invoked if any {@link DataTransferFile files} are present in the {@linkcode DataTransfer}.
+         * Note that {@linkcode DataTransferFile} entries are only created when dropping content from outside the editor, such as
          * from the operating system.
          */
         readonly pasteMimeTypes?: readonly string[];
     }
 
     namespace languages {
+        /**
+         * Registers a new {@linkcode DocumentPasteEditProvider}.
+         *
+         * @param selector A selector that defines the documents this provider applies to.
+         * @param provider A paste editor provider.
+         * @param metadata Additional metadata about the provider.
+         *
+         * @returns A {@link Disposable} that unregisters this provider when disposed of.
+         * @stubbed
+         */
         export function registerDocumentPasteEditProvider(selector: DocumentSelector, provider: DocumentPasteEditProvider, metadata: DocumentPasteProviderMetadata): Disposable;
     }
 }

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

@@ -29,7 +29,16 @@ export module '@theia/plugin' {
         /**
          * Human readable label that describes the edit.
          */
-        label?: string;
+        title?: string;
+
+        /**
+         * {@link DocumentPasteEditKind Kind} of the edit.
+         *
+         * Used to identify specific types of edits.
+         *
+         * TODO: use own type?
+         */
+        kind: DocumentPasteEditKind;
 
         /**
          * The mime type from the {@link DataTransfer} that this edit applies.
@@ -39,21 +48,11 @@ export module '@theia/plugin' {
         /**
          * Controls the ordering or multiple paste edits. If this provider yield to edits, it will be shown lower in the list.
          */
-        yieldTo?: ReadonlyArray<
-            | { readonly extensionId: string; readonly providerId: string }
-            | { readonly mimeType: string }
-        >;
+        yieldTo?: ReadonlyArray<DocumentPasteEditKind>;
     }
 
     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;
+        readonly providedDropEditKinds?: readonly DocumentPasteEditKind[];
 
         /**
          * List of data transfer types that the provider supports.