@codingame/monaco-vscode-api 20.1.0 → 20.2.0

package/vscode/src/vs/workbench/contrib/testing/common/testService.service.d.ts

@@ -12,27 +12,89 @@ import { TestsDiff, ResolvedTestRunRequest, TestMessageFollowupRequest, Internal
 export declare const ITestService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<ITestService>;
 export interface ITestService {
     readonly _serviceBrand: undefined;
+    /**
+    * Fires when the user requests to cancel a test run -- or all runs, if no
+    * runId is given.
+    */
     readonly onDidCancelTestRun: Event<{
         runId: string | undefined;
         taskId: string | undefined;
     }>;
+    /**
+    * Event that fires when the excluded tests change.
+    */
     readonly excluded: TestExclusions;
+    /**
+    * Test collection instance.
+    */
     readonly collection: IMainThreadTestCollection;
+    /**
+    * Event that fires immediately before a diff is processed.
+    */
     readonly onWillProcessDiff: Event<TestsDiff>;
+    /**
+    * Event that fires after a diff is processed.
+    */
     readonly onDidProcessDiff: Event<TestsDiff>;
+    /**
+    * Whether inline editor decorations should be visible.
+    */
     readonly showInlineOutput: MutableObservableValue<boolean>;
+    /**
+    * Registers an interface that represents an extension host..
+    */
     registerExtHost(controller: IMainThreadTestHostProxy): IDisposable;
+    /**
+    * Registers an interface that runs tests for the given provider ID.
+    */
     registerTestController(providerId: string, controller: IMainThreadTestController): IDisposable;
+    /**
+    * Gets a registered test controller by ID.
+    */
     getTestController(controllerId: string): IMainThreadTestController | undefined;
+    /**
+    * Refreshes tests for the controller, or all controllers if no ID is given.
+    */
     refreshTests(controllerId?: string): Promise<void>;
+    /**
+    * Cancels any ongoing test refreshes.
+    */
     cancelRefreshTests(): void;
+    /**
+    * Requests that tests be executed continuously, until the token is cancelled.
+    */
     startContinuousRun(req: ResolvedTestRunRequest, token: CancellationToken): Promise<void>;
+    /**
+    * Requests that tests be executed.
+    */
     runTests(req: AmbiguousRunTestsRequest, token?: CancellationToken): Promise<ITestResult>;
+    /**
+    * Requests that tests be executed.
+    */
     runResolvedTests(req: ResolvedTestRunRequest, token?: CancellationToken): Promise<ITestResult>;
+    /**
+    * Provides followup actions for a test run.
+    */
     provideTestFollowups(req: TestMessageFollowupRequest, token: CancellationToken): Promise<ITestFollowups>;
+    /**
+    * Ensures the test diff from the remote ext host is flushed and waits for
+    * any "busy" tests to become idle before resolving.
+    */
     syncTests(): Promise<void>;
+    /**
+    * Cancels an ongoing test run by its ID, or all runs if no ID is given.
+    */
     cancelTestRun(runId?: string, taskId?: string): void;
+    /**
+    * Publishes a test diff for a controller.
+    */
     publishDiff(controllerId: string, diff: TestsDiff): void;
+    /**
+    * Gets all tests related to the given code position.
+    */
     getTestsRelatedToCode(uri: URI, position: Position, token?: CancellationToken): Promise<InternalTestItem[]>;
+    /**
+    * Gets code related to the given test item.
+    */
     getCodeRelatedToTest(test: InternalTestItem, token?: CancellationToken): Promise<Location[]>;
 }

package/vscode/src/vs/workbench/contrib/testing/common/testTypes.d.ts

@@ -15,6 +15,7 @@ export declare enum TestResultState {
 export declare const testResultStateToContextValues: {
     [K in TestResultState]: string;
 };
+/** note: keep in sync with TestRunProfileKind in vscode.d.ts */
 export declare enum ExtTestRunProfileKind {
     Run = 1,
     Debug = 2,
@@ -38,7 +39,13 @@ export declare const testProfileBitset: {
     4: string;
     8: string;
 };
+/**
+ * List of all test run profile bitset values.
+ */
 export declare const testRunProfileBitsetList: TestRunProfileBitset[];
+/**
+ * DTO for a controller's run profiles.
+ */
 export interface ITestRunProfile {
     controllerId: string;
     profileId: number;
@@ -54,6 +61,10 @@ export interface ITestRunProfileReference {
     profileId: number;
     group: TestRunProfileBitset;
 }
+/**
+ * A fully-resolved request to run tests, passsed between the main thread
+ * and extension host.
+ */
 export interface ResolvedTestRunRequest {
     group: TestRunProfileBitset;
     targets: {
@@ -62,9 +73,14 @@ export interface ResolvedTestRunRequest {
         profileId: number;
     }[];
     exclude?: string[];
+    /** Whether this is a continuous test run */
     continuous?: boolean;
+    /** Whether this was trigged by a user action in UI. Default=true */
     preserveFocus?: boolean;
 }
+/**
+ * Request to the main thread to run a set of tests.
+ */
 export interface ExtensionRunTestsRequest {
     id: string;
     include: string[];
@@ -76,8 +92,16 @@ export interface ExtensionRunTestsRequest {
     };
     persist: boolean;
     preserveFocus: boolean;
+    /** Whether this is a result of a continuous test run request */
     continuous: boolean;
 }
+/**
+ * Request parameters a controller run handler. This is different than
+ * {@link IStartControllerTests}. The latter is used to ask for one or more test
+ * runs tracked directly by the renderer.
+ *
+ * This alone can be used to start an autorun, without a specific associated runId.
+ */
 export interface ICallProfileRunHandler {
     controllerId: string;
     profileId: number;
@@ -85,17 +109,25 @@ export interface ICallProfileRunHandler {
     testIds: string[];
 }
 export declare const isStartControllerTests: (t: ICallProfileRunHandler | IStartControllerTests) => t is IStartControllerTests;
+/**
+ * Request from the main thread to run tests for a single controller.
+ */
 export interface IStartControllerTests extends ICallProfileRunHandler {
     runId: string;
 }
 export interface IStartControllerTestsResult {
     error?: string;
 }
+/**
+ * Location with a fully-instantiated Range and URI.
+ */
 export interface IRichLocation {
     range: Range;
     uri: URI;
 }
+/** Subset of the IUriIdentityService */
 export interface ITestUriCanonicalizer {
+    /** @link import('vs/platform/uriIdentity/common/uriIdentity').IUriIdentityService */
     asCanonicalUri(uri: URI): URI;
 }
 export declare namespace IRichLocation {
@@ -154,6 +186,10 @@ export interface ITestOutputMessage {
     marker?: number;
     location: IRichLocation | undefined;
 }
+/**
+ * Gets the TTY marker ID for either starting or ending
+ * an ITestOutputMessage.marker of the given ID.
+ */
 export declare const getMarkId: (marker: number, start: boolean) => string;
 export declare namespace ITestOutputMessage {
     interface Serialized {
@@ -208,7 +244,11 @@ export declare const denamespaceTestTag: (namespaced: string) => {
 export interface ITestTagDisplayInfo {
     id: string;
 }
+/**
+ * The TestItem from .d.ts, as a plain object without children.
+ */
 export interface ITestItem {
+    /** ID of the test given by the test controller */
     extId: string;
     label: string;
     tags: string[];
@@ -242,9 +282,15 @@ export declare enum TestItemExpandState {
     BusyExpanding = 2,
     Expanded = 3
 }
+/**
+ * TestItem-like shape, but with an ID and children as strings.
+ */
 export interface InternalTestItem {
+    /** Controller ID from whence this test came */
     controllerId: string;
+    /** Expandability state */
     expand: TestItemExpandState;
+    /** Raw test item properties */
     item: ITestItem;
 }
 export declare namespace InternalTestItem {
@@ -255,6 +301,9 @@ export declare namespace InternalTestItem {
     const serialize: (item: Readonly<InternalTestItem>) => Serialized;
     const deserialize: (uriIdentity: ITestUriCanonicalizer, serialized: Serialized) => InternalTestItem;
 }
+/**
+ * A partial update made to an existing InternalTestItem.
+ */
 export interface ITestItemUpdate {
     extId: string;
     expand?: TestItemExpandState;
@@ -270,24 +319,38 @@ export declare namespace ITestItemUpdate {
     const deserialize: (u: Serialized) => ITestItemUpdate;
 }
 export declare const applyTestItemUpdate: (internal: InternalTestItem | ITestItemUpdate, patch: ITestItemUpdate) => void;
+/** Request to an ext host to get followup messages for a test failure. */
 export interface TestMessageFollowupRequest {
     resultId: string;
     extId: string;
     taskIndex: number;
     messageIndex: number;
 }
+/** Request to an ext host to get followup messages for a test failure. */
 export interface TestMessageFollowupResponse {
     id: number;
     title: string;
 }
+/**
+ * Test result item used in the main thread.
+ */
 export interface TestResultItem extends InternalTestItem {
+    /** State of this test in various tasks */
     tasks: ITestTaskState[];
+    /** State of this test as a computation of its tasks */
     ownComputedState: TestResultState;
+    /** Computed state based on children */
     computedState: TestResultState;
+    /** Max duration of the item's tasks (if run directly) */
     ownDuration?: number;
+    /** Whether this test item is outdated */
     retired?: boolean;
 }
 export declare namespace TestResultItem {
+    /**
+     * Serialized version of the TestResultItem. Note that 'retired' is not
+     * included since all hydrated items are automatically retired.
+     */
     interface Serialized extends InternalTestItem.Serialized {
         tasks: ITestTaskState.Serialized[];
         ownComputedState: TestResultState;
@@ -298,16 +361,22 @@ export declare namespace TestResultItem {
     const deserialize: (uriIdentity: ITestUriCanonicalizer, serialized: Serialized) => TestResultItem;
 }
 export interface ISerializedTestResults {
+    /** ID of these test results */
     id: string;
+    /** Time the results were compelted */
     completedAt: number;
+    /** Subset of test result items */
     items: TestResultItem.Serialized[];
+    /** Tasks involved in the run. */
     tasks: {
         id: string;
         name: string | undefined;
         ctrlId: string;
         hasCoverage: boolean;
     }[];
+    /** Human-readable name of the test run. */
     name: string;
+    /** Test trigger informaton */
     request: ResolvedTestRunRequest;
 }
 export interface ITestCoverage {
@@ -342,6 +411,7 @@ export declare namespace IFileCoverage {
     const deserialize: (uriIdentity: ITestUriCanonicalizer, serialized: Serialized) => IFileCoverage;
     const empty: (id: string, uri: URI) => IFileCoverage;
 }
+/** Number of recent runs in which coverage reports should be retained. */
 export declare const KEEP_N_LAST_COVERAGE_REPORTS = 3;
 export declare enum DetailType {
     Declaration = 0,
@@ -401,13 +471,21 @@ export declare namespace IStatementCoverage {
     const deserialize: (serialized: Serialized) => IStatementCoverage;
 }
 export declare enum TestDiffOpType {
+    /** Adds a new test (with children) */
     Add = 0,
+    /** Shallow-updates an existing test */
     Update = 1,
+    /** Ranges of some tests in a document were synced, so it should be considered up-to-date */
     DocumentSynced = 2,
+    /** Removes a test (and all its children) */
     Remove = 3,
+    /** Changes the number of controllers who are yet to publish their collection roots. */
     IncrementPendingExtHosts = 4,
+    /** Retires a test/result */
     Retire = 5,
+    /** Add a new test tag */
     AddTag = 6,
+    /** Remove a test tag */
     RemoveTag = 7
 }
 export type TestsDiffOp = {
@@ -466,40 +544,112 @@ export declare namespace TestsDiffOp {
     const deserialize: (uriIdentity: ITestUriCanonicalizer, u: Serialized) => TestsDiffOp;
     const serialize: (u: Readonly<TestsDiffOp>) => Serialized;
 }
+/**
+ * Context for actions taken in the test explorer view.
+ */
 export interface ITestItemContext {
+    /** Marshalling marker */
     $mid: MarshalledId.TestItemContext;
+    /** Tests and parents from the root to the current items */
     tests: InternalTestItem.Serialized[];
 }
+/**
+ * Context for actions taken in the test explorer view.
+ */
 export interface ITestMessageMenuArgs {
+    /** Marshalling marker */
     $mid: MarshalledId.TestMessageMenuArgs;
+    /** Tests ext ID */
     test: InternalTestItem.Serialized;
+    /** Serialized test message */
     message: ITestMessage.Serialized;
 }
+/**
+ * Request from the ext host or main thread to indicate that tests have
+ * changed. It's assumed that any item upserted *must* have its children
+ * previously also upserted, or upserted as part of the same operation.
+ * Children that no longer exist in an upserted item will be removed.
+ */
 export type TestsDiff = TestsDiffOp[];
+/**
+ * @private
+ */
 export interface IncrementalTestCollectionItem extends InternalTestItem {
     children: Set<string>;
 }
+/**
+ * The IncrementalChangeCollector is used in the IncrementalTestCollection
+ * and called with diff changes as they're applied. This is used in the
+ * ext host to create a cohesive change event from a diff.
+ */
 export interface IncrementalChangeCollector<T> {
+    /**
+     * A node was added.
+     */
     add?(node: T): void;
+    /**
+     * A node in the collection was updated.
+     */
     update?(node: T): void;
+    /**
+     * A node was removed.
+     */
     remove?(node: T, isNestedOperation: boolean): void;
+    /**
+     * Called when the diff has been applied.
+     */
     complete?(): void;
 }
+/**
+ * Maintains tests in this extension host sent from the main thread.
+ */
 export declare abstract class AbstractIncrementalTestCollection<T extends IncrementalTestCollectionItem> {
     private readonly uriIdentity;
     private readonly _tags;
+    /**
+     * Map of item IDs to test item objects.
+     */
     protected readonly items: Map<string, T>;
+    /**
+     * ID of test root items.
+     */
     protected readonly roots: Set<T>;
+    /**
+     * Number of 'busy' controllers.
+     */
     protected busyControllerCount: number;
+    /**
+     * Number of pending roots.
+     */
     protected pendingRootCount: number;
+    /**
+     * Known test tags.
+     */
     readonly tags: ReadonlyMap<string, ITestTagDisplayInfo>;
     constructor(uriIdentity: ITestUriCanonicalizer);
+    /**
+     * Applies the diff to the collection.
+     */
     apply(diff: TestsDiff): void;
     protected add(item: InternalTestItem, changes: IncrementalChangeCollector<T>): T | undefined;
     protected update(patch: ITestItemUpdate, changes: IncrementalChangeCollector<T>): T | undefined;
     protected remove(itemId: string, changes: IncrementalChangeCollector<T>): void;
+    /**
+     * Called when the extension signals a test result should be retired.
+     */
     protected retireTest(testId: string): void;
+    /**
+     * Updates the number of test root sources who are yet to report. When
+     * the total pending test roots reaches 0, the roots for all controllers
+     * will exist in the collection.
+     */
     updatePendingRoots(delta: number): void;
+    /**
+     * Called before a diff is applied to create a new change collector.
+     */
     protected createChangeCollector(): IncrementalChangeCollector<T>;
+    /**
+     * Creates a new item for the collection from the internal test item.
+     */
     protected abstract createItem(internal: InternalTestItem, parent?: T): T;
 }

package/vscode/src/vs/workbench/contrib/testing/common/testingContinuousRunService.service.d.ts

@@ -3,14 +3,50 @@ import { ITestRunProfile, TestRunProfileBitset } from "./testTypes.js";
 export declare const ITestingContinuousRunService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<ITestingContinuousRunService>;
 export interface ITestingContinuousRunService {
     readonly _serviceBrand: undefined;
+    /**
+    * Gets a list of the last test profiles that were continuously run in the workspace.
+    */
     readonly lastRunProfileIds: ReadonlySet<number>;
+    /**
+    * Fired when a test is added or removed from continous run, or when
+    * enablement is changed globally.
+    */
     onDidChange: Event<string | undefined>;
+    /**
+    * Gets whether continous run is specifically enabled for the given test ID.
+    */
     isSpecificallyEnabledFor(testId: string): boolean;
+    /**
+    * Gets whether continous run is specifically enabled for
+    * the given test ID, or any of its parents.
+    */
     isEnabledForAParentOf(testId: string): boolean;
+    /**
+    * Gets whether continous run is specifically enabled for
+    * the given test ID, or any of its parents.
+    */
     isEnabledForAChildOf(testId: string): boolean;
+    /**
+    * Gets whether continuous run is turned on for the given profile.
+    */
     isEnabledForProfile(profile: ITestRunProfile): boolean;
+    /**
+    * Gets whether it's enabled at all.
+    */
     isEnabled(): boolean;
+    /**
+    * Starts a continuous auto run with a specific set of profiles, or all
+    * default profiles in a group. Globally if no test is given,
+    * for a specific test otherwise.
+    */
     start(profile: ITestRunProfile[] | TestRunProfileBitset, testId?: string): void;
+    /**
+    * Stops a continuous run for the given test profile.
+    */
     stopProfile(profile: ITestRunProfile): void;
+    /**
+    * Stops any continuous run
+    * Globally if no test is given, for a specific test otherwise.
+    */
     stop(testId?: string): void;
 }

package/vscode/src/vs/workbench/contrib/testing/common/testingDecorations.service.d.ts

@@ -6,12 +6,31 @@ import { ITestMessage } from "./testTypes.js";
 export declare const ITestingDecorationsService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<ITestingDecorationsService>;
 export interface ITestingDecorationsService {
     _serviceBrand: undefined;
+    /**
+    * Fires when something happened to change decorations in an editor.
+    * Interested consumers should call {@link syncDecorations} to update them.
+    */
     onDidChange: Event<void>;
+    /**
+    * Signals the code underlying a test message has changed, and it should
+    * no longer be decorated in the source.
+    */
     invalidateResultMessage(message: ITestMessage): void;
+    /**
+    * Ensures decorations in the given document URI are up to date,
+    * and returns them.
+    */
     syncDecorations(resource: URI): Iterable<ITestDecoration> & {
         readonly size: number;
         getById(decorationId: string): ITestDecoration | undefined;
     };
+    /**
+    * Gets the range where a test ID is displayed, in the given URI.
+    * Returns undefined if there's no such decoration.
+    */
     getDecoratedTestPosition(resource: URI, testId: string): Position | undefined;
+    /**
+    * Sets that alternative actions are displayed on the model.
+    */
     updateDecorationsAlternateAction(resource: URI, isAlt: boolean): void;
 }

package/vscode/src/vs/workbench/contrib/testing/common/testingPeekOpener.d.ts

@@ -1,6 +1,8 @@
 import { ITextEditorOptions } from "../../../../platform/editor/common/editor.js";
 import { IEditor } from "../../../../editor/common/editorCommon.js";
 export interface IShowResultOptions {
+    /** Reveal the peek, if configured, in the given editor */
     inEditor?: IEditor;
+    /** Editor options, if a new editor is opened */
     options?: Partial<ITextEditorOptions>;
 }

package/vscode/src/vs/workbench/contrib/testing/common/testingPeekOpener.service.d.ts

@@ -6,11 +6,29 @@ import { ITestResult } from "@codingame/monaco-vscode-6845754f-e617-5ed9-8aaa-6c
 import { TestResultItem } from "./testTypes.js";
 export interface ITestingPeekOpener {
     _serviceBrand: undefined;
+    /** Whether test history should be shown in the results output. */
     historyVisible: MutableObservableValue<boolean>;
+    /**
+    * Tries to peek the first test error, if the item is in a failed state.
+    * @returns a boolean indicating whether a peek was opened
+    */
     tryPeekFirstError(result: ITestResult, test: TestResultItem, options?: Partial<ITextEditorOptions>): boolean;
+    /**
+    * Peeks at the given test message uri.
+    * @returns a boolean indicating whether a peek was opened
+    */
     peekUri(uri: URI, options?: IShowResultOptions): boolean;
+    /**
+    * Opens the currently selected message in an editor.
+    */
     openCurrentInEditor(): void;
+    /**
+    * Opens the peek. Shows any available message.
+    */
     open(): void;
+    /**
+    * Closes peeks for all visible editors.
+    */
     closeAllPeeks(): void;
 }
 export declare const ITestingPeekOpener: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<ITestingPeekOpener>;

package/vscode/src/vs/workbench/contrib/timeline/common/timeline.d.ts

@@ -10,7 +10,14 @@ import { IMarkdownString } from "../../../../base/common/htmlContent.js";
 export declare function toKey(extension: ExtensionIdentifier | string, source: string): string;
 export declare const TimelinePaneId = "timeline";
 export interface TimelineItem {
+    /**
+     * The handle of the item must be unique across all the
+     * timeline items provided by this source.
+     */
     handle: string;
+    /**
+     * The identifier of the timeline provider this timeline item is from.
+     */
     source: string;
     id?: string;
     label: string;
@@ -28,8 +35,18 @@ export interface TimelineItem {
     hideRelativeTime?: boolean;
 }
 export interface TimelineChangeEvent {
+    /**
+     * The identifier of the timeline provider this event is from.
+     */
     id: string;
+    /**
+     * The resource that has timeline entries changed or `undefined`
+     * if not known.
+     */
     uri: URI | undefined;
+    /**
+     * Whether to drop all timeline entries and refresh them again.
+     */
     reset: boolean;
 }
 export interface TimelineOptions {
@@ -42,6 +59,9 @@ export interface TimelineOptions {
     cacheResults?: boolean;
 }
 export interface Timeline {
+    /**
+     * The identifier of the timeline provider this timeline is from.
+     */
     source: string;
     items: TimelineItem[];
     paging?: {
@@ -57,8 +77,17 @@ export interface TimelineSource {
     label: string;
 }
 export interface TimelineProviderDescriptor {
+    /**
+     * An identifier of the source of the timeline items. This can be used to filter sources.
+     */
     id: string;
+    /**
+     * A human-readable string describing the source of the timeline items. This can be used as the display label when filtering sources.
+     */
     label: string;
+    /**
+     * The resource scheme(s) this timeline provider is providing entries for.
+     */
     scheme: string | string[];
 }
 export interface TimelineProvidersChangeEvent {

package/vscode/src/vs/workbench/contrib/webview/browser/webview.service.d.ts

@@ -3,9 +3,27 @@ import { IWebview, WebviewInitInfo, IWebviewElement, IOverlayWebview } from "@co
 export declare const IWebviewService: import("../../../../platform/instantiation/common/instantiation.js").ServiceIdentifier<IWebviewService>;
 export interface IWebviewService {
     readonly _serviceBrand: undefined;
+    /**
+    * The currently focused webview.
+    */
     readonly activeWebview: IWebview | undefined;
+    /**
+    * All webviews.
+    */
     readonly webviews: Iterable<IWebview>;
+    /**
+    * Fired when the currently focused webview changes.
+    */
     readonly onDidChangeActiveWebview: Event<IWebview | undefined>;
+    /**
+    * Create a basic webview dom element.
+    */
     createWebviewElement(initInfo: WebviewInitInfo): IWebviewElement;
+    /**
+    * Create a lazily created webview element that is overlaid on top of another element.
+    *
+    * Allows us to avoid re-parenting the webview (which destroys its contents) when
+    * moving webview around the workbench.
+    */
     createWebviewOverlay(initInfo: WebviewInitInfo): IOverlayWebview;
 }

package/vscode/src/vs/workbench/contrib/webview/common/webview.d.ts

@@ -3,8 +3,27 @@ export interface WebviewRemoteInfo {
     readonly isRemote: boolean;
     readonly authority: string | undefined;
 }
+/**
+ * Root from which resources in webviews are loaded.
+ *
+ * This is hardcoded because we never expect to actually hit it. Instead these requests
+ * should always go to a service worker.
+ */
 export declare const webviewResourceBaseHost = "vscode-cdn.net";
 export declare const webviewRootResourceAuthority = "vscode-resource.vscode-cdn.net";
 export declare const webviewGenericCspSource = "'self' https://*.vscode-cdn.net";
+/**
+ * Construct a uri that can load resources inside a webview
+ *
+ * We encode the resource component of the uri so that on the main thread
+ * we know where to load the resource from (remote or truly local):
+ *
+ * ```txt
+ * ${scheme}+${resource-authority}.vscode-resource.vscode-cdn.net/${path}
+ * ```
+ *
+ * @param resource Uri of the resource to load.
+ * @param remoteInfo Optional information about the remote that specifies where `resource` should be resolved from.
+ */
 export declare function asWebviewUri(resource: URI, remoteInfo?: WebviewRemoteInfo): URI;
 export declare function decodeAuthority(authority: string): string;