@codingame/monaco-vscode-chat-service-override 20.1.1 → 20.2.0

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/headerBase.d.ts

@@ -8,29 +8,100 @@ import { type TDiagnostic } from "./diagnostics.js";
 import { FrontMatterRecord } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
 import { FrontMatterHeader } from "../../codecs/base/markdownExtensionsCodec/tokens/frontMatterHeader.js";
 import { PromptDescriptionMetadata } from "./metadata/description.js";
+/**
+ * A metadata utility class "dehydrated" into a plain data object with
+ * semi-primitive record values (string, boolean, string[], boolean[], etc.).
+ */
 export type TDehydrated<T extends IHeaderMetadata> = {
     [K in keyof T]: T[K] extends IMetadataRecord<infer U> ? (U extends undefined ? undefined : NonNullable<U>) : undefined;
 };
+/**
+ * Metadata defined in the prompt header.
+ */
 export interface IHeaderMetadata {
+    /**
+     * Description metadata in the prompt header.
+     */
     description: PromptDescriptionMetadata;
 }
+/**
+ * Metadata for prompt/instruction/mode files.
+ */
 export type THeaderMetadata = Partial<TDehydrated<IHeaderMetadata>>;
+/**
+ * Metadata defined in the header of prompt/instruction/mode files.
+ */
 export type TMetadata = TPromptMetadata | TModeMetadata | TInstructionsMetadata;
+/**
+ * Base class for prompt/instruction/mode headers.
+ */
 export declare abstract class HeaderBase<TMetadata extends IHeaderMetadata> extends Disposable {
     readonly token: FrontMatterHeader;
     readonly languageId: string;
+    /**
+     * Underlying decoder for a Front Matter header.
+     */
     private readonly stream;
+    /**
+     * Metadata records.
+     */
     protected readonly meta: Partial<TMetadata>;
+    /**
+     * Data object with all header's metadata records.
+     */
     get metadata(): Partial<TDehydrated<TMetadata>>;
+    /**
+     * A copy of metadata object with utility classes as values
+     * for each of prompt header's record.
+     *
+     * Please use {@link metadata} instead if all you need to read is
+     * the plain "data" object representation of valid metadata records.
+     */
     get metadataUtility(): Partial<TMetadata>;
+    /**
+     * List of all unique metadata record names.
+     */
     private readonly recordNames;
+    /**
+     * List of all issues found while parsing the prompt header.
+     */
     protected readonly issues: TDiagnostic[];
+    /**
+     * List of all diagnostic issues found while parsing
+     * the prompt header.
+     */
     get diagnostics(): readonly TDiagnostic[];
+    /**
+     * Full range of the header in the original document.
+     */
     get range(): Range;
     constructor(token: FrontMatterHeader, languageId: string);
+    /**
+     * Process a front matter record token, which includes:
+     *  - validation of the record and whether it is compatible with other header records
+     *  - adding validation-related diagnostic messages to the {@link issues} list
+     *  - setting associated utility class for the record on the {@link meta} object
+     *
+     * @returns a boolean flag that indicates whether the token was handled and therefore
+     *          should not be processed any further.
+     */
     protected abstract handleToken(token: FrontMatterRecord): boolean;
+    /**
+     * Process front matter tokens, converting them into
+     * well-known prompt metadata records.
+     */
     private onData;
+    /**
+     * Process errors from the underlying front matter decoder.
+     */
     private onError;
+    /**
+     * Promise that resolves when parsing process of
+     * the prompt header completes.
+     */
     get settled(): Promise<boolean>;
+    /**
+     * Starts the parsing process of the prompt header.
+     */
     start(): this;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/instructionsHeader.d.ts

@@ -2,12 +2,24 @@ import { PromptApplyToMetadata } from "./metadata/applyTo.js";
 import { HeaderBase, IHeaderMetadata, type TDehydrated } from "./headerBase.js";
 import { PromptsType } from "@codingame/monaco-vscode-e28ac690-06d5-5ee9-92d1-02df70296354-common/vscode/vs/workbench/contrib/chat/common/promptSyntax/promptTypes";
 import { FrontMatterRecord } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Metadata utility object for instruction files.
+ */
 interface IInstructionsMetadata extends IHeaderMetadata {
+    /**
+     * Chat 'applyTo' metadata in the prompt header.
+     */
     applyTo: PromptApplyToMetadata;
 }
+/**
+ * Metadata for instruction files.
+ */
 export type TInstructionsMetadata = Partial<TDehydrated<IInstructionsMetadata>> & {
     promptType: PromptsType.instructions;
 };
+/**
+ * Header object for instruction files.
+ */
 export declare class InstructionsHeader extends HeaderBase<IInstructionsMetadata> {
     protected handleToken(token: FrontMatterRecord): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/applyTo.d.ts

@@ -1,10 +1,20 @@
 import { PromptStringMetadata } from "./base/string.js";
 import { PromptMetadataDiagnostic } from "../diagnostics.js";
 import { FrontMatterRecord, FrontMatterToken } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Prompt `applyTo` metadata record inside the prompt header.
+ */
 export declare class PromptApplyToMetadata extends PromptStringMetadata {
     constructor(recordToken: FrontMatterRecord, languageId: string);
     get recordName(): string;
     validate(): readonly PromptMetadataDiagnostic[];
+    /**
+     * Check if a provided string contains a valid glob pattern.
+     */
     private isValidGlob;
+    /**
+     * Check if a provided front matter token is a metadata record
+     * with name equal to `applyTo`.
+     */
     static isApplyToRecord(token: FrontMatterToken): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/base/enum.d.ts

@@ -1,10 +1,23 @@
 import { PromptStringMetadata } from "./string.js";
 import { PromptMetadataDiagnostic } from "../../diagnostics.js";
 import { FrontMatterRecord } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Enum type is the special case of the {@link PromptStringMetadata string}
+ * type that can take only a well-defined set of {@link validValues}.
+ */
 export declare abstract class PromptEnumMetadata<TValidValues extends string = string> extends PromptStringMetadata {
     private readonly validValues;
     constructor(validValues: readonly TValidValues[], expectedRecordName: string, recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Valid enum value or 'undefined'.
+     */
     private enumValue;
+    /**
+     * Valid enum value or 'undefined'.
+     */
     get value(): TValidValues | undefined;
+    /**
+     * Validate the metadata record has an allowed value.
+     */
     validate(): readonly PromptMetadataDiagnostic[];
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/base/record.d.ts

@@ -1,23 +1,65 @@
 import { Range } from "@codingame/monaco-vscode-api/vscode/vs/editor/common/core/range";
 import { PromptMetadataDiagnostic, PromptMetadataError, PromptMetadataWarning } from "../../diagnostics.js";
 import { FrontMatterRecord } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Supported primitive types for metadata values in a prompt header.
+ */
 type TMetadataPrimitive = string | boolean;
+/**
+ * Supported metadata values in a prompt header.
+ */
 type TMetadataValue = TMetadataPrimitive | TMetadataPrimitive[];
+/**
+ * Interface for a generic metadata record in the prompt header.
+ */
 export interface IMetadataRecord<T extends TMetadataValue> {
+    /**
+     * Value of a metadata record. If the value is not defined, it usually
+     * means that a record is present but its value is not set or valid.
+     */
     readonly value: T | undefined;
 }
+/**
+ * Abstract class for all metadata records in the prompt header.
+ */
 export declare abstract class PromptMetadataRecord<TValue extends TMetadataValue> implements IMetadataRecord<TValue> {
     protected readonly expectedRecordName: string;
     protected readonly recordToken: FrontMatterRecord;
     protected readonly languageId: string;
+    /**
+     * Private field for tracking all diagnostic issues
+     * related to this metadata record.
+     */
     protected readonly issues: PromptMetadataDiagnostic[];
+    /**
+     * Full range of the metadata's record text in the prompt header.
+     */
     get range(): Range;
     constructor(expectedRecordName: string, recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Name of the metadata record.
+     */
     get recordName(): string;
+    /**
+     * Validate the metadata record and collect all issues
+     * related to its content.
+     */
     abstract validate(): readonly PromptMetadataDiagnostic[];
+    /**
+     * List of all diagnostic issues related to this metadata record.
+     */
     get diagnostics(): readonly PromptMetadataDiagnostic[];
+    /**
+     * Get the value of the metadata record.
+     */
     abstract get value(): TValue | undefined;
+    /**
+     * List of all `error` issue diagnostics.
+     */
     get errorDiagnostics(): readonly PromptMetadataError[];
+    /**
+     * List of all `warning` issue diagnostics.
+     */
     get warningDiagnostics(): readonly PromptMetadataWarning[];
 }
 export {};

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/base/string.d.ts

@@ -2,9 +2,21 @@ import { PromptMetadataRecord } from "./record.js";
 import { PromptMetadataDiagnostic } from "../../diagnostics.js";
 import { FrontMatterSequence } from "../../../../codecs/base/frontMatterCodec/tokens/frontMatterSequence.js";
 import { FrontMatterRecord, FrontMatterString } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Base class for all metadata records with a `string` value.
+ */
 export declare abstract class PromptStringMetadata extends PromptMetadataRecord<string> {
+    /**
+     * Value token reference of the record.
+     */
     protected valueToken: FrontMatterString | FrontMatterSequence | undefined;
+    /**
+     * String value of a metadata record.
+     */
     get value(): string | undefined;
     constructor(expectedRecordName: string, recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Validate the metadata record has a 'string' value.
+     */
     validate(): readonly PromptMetadataDiagnostic[];
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/description.d.ts

@@ -1,7 +1,14 @@
 import { PromptStringMetadata } from "./base/string.js";
 import { FrontMatterRecord, FrontMatterToken } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Prompt `description` metadata record inside the prompt header.
+ */
 export declare class PromptDescriptionMetadata extends PromptStringMetadata {
     get recordName(): string;
     constructor(recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Check if a provided front matter token is a metadata record
+     * with name equal to `description`.
+     */
     static isDescriptionRecord(token: FrontMatterToken): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/mode.d.ts

@@ -1,7 +1,14 @@
 import { ChatModeKind } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/constants";
 import { PromptEnumMetadata } from "./base/enum.js";
 import { FrontMatterRecord, FrontMatterToken } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
+/**
+ * Prompt `mode` metadata record inside the prompt header.
+ */
 export declare class PromptModeMetadata extends PromptEnumMetadata<ChatModeKind> {
     constructor(recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Check if a provided front matter token is a metadata record
+     * with name equal to `mode`.
+     */
     static isModeRecord(token: FrontMatterToken): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/model.d.ts

@@ -3,5 +3,9 @@ import { PromptStringMetadata } from "./base/string.js";
 export declare class PromptModelMetadata extends PromptStringMetadata {
     get recordName(): string;
     constructor(recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Check if a provided front matter token is a metadata record
+     * with name equal to `description`.
+     */
     static isModelRecord(token: FrontMatterToken): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/metadata/tools.d.ts

@@ -2,14 +2,40 @@ import { PromptMetadataRecord } from "./base/record.js";
 import { PromptMetadataDiagnostic } from "../diagnostics.js";
 import { FrontMatterArray, FrontMatterRecord, FrontMatterToken } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
 import { Range } from "@codingame/monaco-vscode-api/vscode/vs/editor/common/core/range";
+/**
+ * Prompt `tools` metadata record inside the prompt header.
+ */
 export declare class PromptToolsMetadata extends PromptMetadataRecord<string[]> {
+    /**
+     * List of all valid tool names that were found in
+     * this metadata record.
+     */
     get value(): string[] | undefined;
     get recordName(): string;
+    /**
+     * Value token reference of the record.
+     */
     protected valueToken: FrontMatterArray | undefined;
+    /**
+     * List of all valid tool names that were found in
+     * this metadata record.
+     */
     private validToolNames;
     constructor(recordToken: FrontMatterRecord, languageId: string);
+    /**
+     * Validate the metadata record and collect all issues
+     * related to its content.
+     */
     validate(): readonly PromptMetadataDiagnostic[];
     getToolRange(toolName: string): Range | undefined;
+    /**
+     * Validate an individual provided value token that is used
+     * for a tool name.
+     */
     private validateToolName;
+    /**
+     * Check if a provided front matter token is a metadata record
+     * with name equal to `tools`.
+     */
     static isToolsRecord(token: FrontMatterToken): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/modeHeader.d.ts

@@ -3,13 +3,28 @@ import { PromptsType } from "@codingame/monaco-vscode-e28ac690-06d5-5ee9-92d1-02
 import { FrontMatterRecord } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/codecs/base/frontMatterCodec/tokens/index";
 import { PromptModelMetadata } from "./metadata/model.js";
 import { PromptToolsMetadata } from "./metadata/tools.js";
+/**
+ * Metadata utility object for mode files.
+ */
 interface IModeMetadata extends IHeaderMetadata {
+    /**
+     * Tools metadata in the mode header.
+     */
     tools: PromptToolsMetadata;
+    /**
+     * Chat model metadata in the mode header.
+     */
     model: PromptModelMetadata;
 }
+/**
+ * Metadata for mode files.
+ */
 export type TModeMetadata = Partial<TDehydrated<IModeMetadata>> & {
     promptType: PromptsType.mode;
 };
+/**
+ * Header object for mode files.
+ */
 export declare class ModeHeader extends HeaderBase<IModeMetadata> {
     protected handleToken(token: FrontMatterRecord): boolean;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptHeader/promptHeader.d.ts

@@ -4,16 +4,42 @@ import { FrontMatterRecord } from "@codingame/monaco-vscode-api/vscode/vs/workbe
 import { PromptModelMetadata } from "./metadata/model.js";
 import { PromptToolsMetadata } from "./metadata/tools.js";
 import { PromptModeMetadata } from "./metadata/mode.js";
+/**
+ * Metadata utility object for prompt files.
+ */
 export interface IPromptMetadata extends IHeaderMetadata {
+    /**
+     * Tools metadata in the prompt header.
+     */
     tools: PromptToolsMetadata;
+    /**
+     * Chat mode metadata in the prompt header.
+     */
     mode: PromptModeMetadata;
+    /**
+     * Chat model metadata in the prompt header.
+     */
     model: PromptModelMetadata;
 }
+/**
+ * Metadata for prompt files.
+ */
 export type TPromptMetadata = Partial<TDehydrated<IPromptMetadata>> & {
     promptType: PromptsType.prompt;
 };
+/**
+ * Header object for prompt files.
+ */
 export declare class PromptHeader extends HeaderBase<IPromptMetadata> {
     protected handleToken(token: FrontMatterRecord): boolean;
+    /**
+     * Check if value of `tools` and `mode` metadata
+     * are compatible with each other.
+     */
     private get toolsAndModeCompatible();
+    /**
+     * Validate that the `tools` and `mode` metadata are compatible
+     * with each other. If not, add a warning diagnostic.
+     */
     private validateToolsAndModeCompatibility;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/promptParser.d.ts

@@ -5,8 +5,18 @@ import { BasePromptParser, IPromptParserOptions } from "./basePromptParser.js";
 import { IModelService } from "@codingame/monaco-vscode-api/vscode/vs/editor/common/services/model.service";
 import { IInstantiationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/instantiation/common/instantiation";
 import { IWorkbenchEnvironmentService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/environment/common/environmentService.service";
+/**
+ * General prompt parser class that automatically infers a prompt
+ * contents provider type by the type of provided prompt URI.
+ */
 export declare class PromptParser extends BasePromptParser<IPromptContentsProvider> {
+    /**
+     * Underlying prompt contents provider instance.
+     */
     private readonly contentsProvider;
     constructor(uri: URI, options: IPromptParserOptions, logService: ILogService, modelService: IModelService, instaService: IInstantiationService, envService: IWorkbenchEnvironmentService);
+    /**
+     * Returns a string representation of this object.
+     */
     toString(): string;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/textModelPromptParser.d.ts

@@ -4,7 +4,14 @@ import { BasePromptParser, IPromptParserOptions } from "./basePromptParser.js";
 import { TextModelContentsProvider } from "../contentProviders/textModelContentsProvider.js";
 import { IInstantiationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/instantiation/common/instantiation";
 import { IWorkbenchEnvironmentService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/services/environment/common/environmentService.service";
+/**
+ * Class capable of parsing prompt syntax out of a provided text model,
+ * including all the nested child file references it may have.
+ */
 export declare class TextModelPromptParser extends BasePromptParser<TextModelContentsProvider> {
     constructor(model: ITextModel, options: IPromptParserOptions, instantiationService: IInstantiationService, envService: IWorkbenchEnvironmentService, logService: ILogService);
+    /**
+     * Returns a string representation of this object.
+     */
     toString(): string;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/parsers/topError.d.ts

@@ -1,4 +1,7 @@
 import { ITopError } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/parsers/types";
+/**
+ * The top-most error of the reference tree.
+ */
 export declare class TopError implements ITopError {
     readonly originalError: ITopError["originalError"];
     readonly errorSubject: ITopError["errorSubject"];

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/promptFileContributions.d.ts

@@ -1,3 +1,9 @@
 import { IWorkbenchContribution } from "@codingame/monaco-vscode-api/vscode/vs/workbench/common/contributions";
+/**
+ * Function that registers all prompt-file related contributions.
+ */
 export declare function registerPromptFileContributions(): void;
+/**
+ * Type for a generic workbench contribution.
+ */
 export type TContribution = new (...args: any[]) => IWorkbenchContribution;

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/service/promptsServiceImpl.d.ts

@@ -14,6 +14,9 @@ import type { IChatPromptSlashCommand, ICustomChatMode, IPromptParserResult, IPr
 import { IPromptsService } from "@codingame/monaco-vscode-api/vscode/vs/workbench/contrib/chat/common/promptSyntax/service/promptsService.service";
 import { ILanguageService } from "@codingame/monaco-vscode-api/vscode/vs/editor/common/languages/language.service";
 import { IConfigurationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/configuration/common/configuration.service";
+/**
+ * Provides prompt services.
+ */
 export declare class PromptsService extends Disposable implements IPromptsService {
     readonly logger: ILogService;
     private readonly labelService;
@@ -23,13 +26,34 @@ export declare class PromptsService extends Disposable implements IPromptsServic
     private readonly languageService;
     private readonly configurationService;
     readonly _serviceBrand: undefined;
+    /**
+     * Cache of text model content prompt parsers.
+     */
     private readonly cache;
+    /**
+     * Prompt files locator utility.
+     */
     private readonly fileLocator;
+    /**
+     * Cached custom modes. Caching only happens if the `onDidChangeCustomChatModes` event is used.
+     */
     private cachedCustomChatModes;
+    /**
+     * Lazily created event that is fired when the custom chat modes change.
+     */
     private onDidChangeCustomChatModesEvent;
     constructor(logger: ILogService, labelService: ILabelService, modelService: IModelService, instantiationService: IInstantiationService, userDataService: IUserDataProfileService, languageService: ILanguageService, configurationService: IConfigurationService);
+    /**
+     * Emitter for the custom chat modes change event.
+     */
     get onDidChangeCustomChatModes(): Event<void>;
     getPromptFileType(uri: URI): PromptsType | undefined;
+    /**
+     * @throws {Error} if:
+     * 	- the provided model is disposed
+     * 	- newly created parser is disposed immediately on initialization.
+     * 	  See factory function in the {@link constructor} for more info.
+     */
     getSyntaxParserFor(model: ITextModel): TextModelPromptParser & {
         isDisposed: false;
     };

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/utils/objectCache.d.ts

@@ -1,13 +1,96 @@
 import { Disposable } from "@codingame/monaco-vscode-api/vscode/vs/base/common/lifecycle";
 import { ObservableDisposable } from "./observableDisposable.js";
+/**
+ * Generic cache for object instances. Guarantees to return only non-disposed
+ * objects from the {@linkcode get} method. If a requested object is not yet
+ * in the cache or is disposed already, the {@linkcode factory} callback is
+ * called to create a new object.
+ *
+ * @throws if {@linkcode factory} callback returns a disposed object.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * // a class that will be used as a cache key; the key can be of any
+ * // non-nullable type, including primitives like `string` or `number`,
+ * // but in this case we use an object pointer as a key
+ * class KeyObject {}
+ *
+ * // a class for testing purposes
+ * class TestObject extends ObservableDisposable {
+ *   constructor(
+ *     public readonly id: KeyObject,
+ *   ) {}
+ * };
+ *
+ * // create an object cache instance providing it a factory function that
+ * // is responsible for creating new objects based on the provided key if
+ * // the cache does not contain the requested object yet or an existing
+ * // object is already disposed
+ * const cache = new ObjectCache<TestObject, KeyObject>((key) => {
+ *   // create a new test object based on the provided key
+ *   return new TestObject(key);
+ * });
+ *
+ * // create two keys
+ * const key1 = new KeyObject();
+ * const key2 = new KeyObject();
+ *
+ * // get an object from the cache by its key
+ * const object1 = cache.get(key1); // returns a new test object
+ *
+ * // validate that the new object has the correct key
+ * assert(
+ *   object1.id === key1,
+ *   'Object 1 must have correct ID.',
+ * );
+ *
+ * // returns the same cached test object
+ * const object2 = cache.get(key1);
+ *
+ * // validate that the same exact object is returned from the cache
+ * assert(
+ *   object1 === object2,
+ *   'Object 2 the same cached object as object 1.',
+ * );
+ *
+ * // returns a new test object
+ * const object3 = cache.get(key2);
+ *
+ * // validate that the new object has the correct key
+ * assert(
+ *   object3.id === key2,
+ *   'Object 3 must have correct ID.',
+ * );
+ *
+ * assert(
+ *   object3 !== object1,
+ *   'Object 3 must be a new object.',
+ * );
+ * ```
+ */
 export declare class ObjectCache<TValue extends ObservableDisposable, TKey extends NonNullable<unknown> = string> extends Disposable {
     private readonly factory;
     private readonly cache;
     constructor(factory: (key: TKey) => TValue & {
         isDisposed: false;
     });
+    /**
+     * Get an existing object from the cache. If a requested object is not yet
+     * in the cache or is disposed already, the {@linkcode factory} callback is
+     * called to create a new object.
+     *
+     * @throws if {@linkcode factory} callback returns a disposed object.
+     * @param key - ID of the object in the cache
+     */
     get(key: TKey): TValue & {
         isDisposed: false;
     };
+    /**
+     * Remove an object from the cache by its key.
+     *
+     * @param key ID of the object to remove.
+     * @param dispose Whether the removed object must be disposed.
+     */
     remove(key: TKey, dispose: boolean): this;
 }

package/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/utils/observableDisposable.d.ts

@@ -1,16 +1,47 @@
 import { Disposable, IDisposable } from "@codingame/monaco-vscode-api/vscode/vs/base/common/lifecycle";
+/**
+* @deprecated do not use this, https://github.com/microsoft/vscode/issues/248366
+ */
 export declare abstract class ObservableDisposable extends Disposable {
+    /**
+     * Underlying disposables store this object relies on.
+     */
     private readonly store;
+    /**
+     * Check if the current object is already has been disposed.
+     */
     get isDisposed(): boolean;
+    /**
+     * The event is fired when this object is disposed.
+     * Note! Executes the callback immediately if already disposed.
+     *
+     * @param callback The callback function to be called on updates.
+     */
     onDispose(callback: () => void): IDisposable;
+    /**
+     * Adds disposable object(s) to the list of disposables
+     * that will be disposed with this object.
+     */
     addDisposables(...disposables: IDisposable[]): this;
+    /**
+     * Assert that the current object was not yet disposed.
+     *
+     * @throws If the current object was already disposed.
+     * @param error Error message or error object to throw if assertion fails.
+     */
     assertNotDisposed(error: string | Error): asserts this is TNotDisposed<this>;
 }
+/**
+ * @deprecated do not use this, https://github.com/microsoft/vscode/issues/248366
+ */
 type TNotDisposed<TObject extends {
     isDisposed: boolean;
 }> = TObject & {
     isDisposed: false;
 };
+/**
+ * @deprecated do not use this, https://github.com/microsoft/vscode/issues/248366
+ */
 export declare function assertNotDisposed<TObject extends {
     isDisposed: boolean;
 }>(object: TObject, error: string | Error): asserts object is TNotDisposed<TObject>;