add more doc comments

Author: legomushroom

src/vs/workbench/contrib/chat/common/promptFileReferenceErrors.ts

@@ -135,7 +135,6 @@ export class RecursiveReference extends ResolveError {
 			uri,
 			`Recursive references found: ${pathString}.`,
 		);
-		this.recursivePathString = pathString;
 	}
 
 	/**
@@ -145,6 +144,14 @@ export class RecursiveReference extends ResolveError {
 		filename: 'basename' | 'fullpath',
 		pathJoinCharacter: string = DEFAULT_RECURSIVE_PATH_JOIN_CHAR,
 	): string {
+		/**
+		 * TODO: @lego - this not currently true though
+		 * TODO: @lego - cache
+		 */
+		if (filename === 'fullpath' && pathJoinCharacter === DEFAULT_RECURSIVE_PATH_JOIN_CHAR) {
+			return this.recursivePathString;
+		}
+
 		return this.recursivePath
 			.map((path) => {
 				if (filename === 'fullpath') {
@@ -176,6 +183,8 @@ export class RecursiveReference extends ResolveError {
 			return false;
 		}
 
+		// TODO: @lego - check array lengths first
+
 		// performance optimization - if the paths lengths don't match,
 		// no need to compare entire strings as they must be different
 		if (this.recursivePathString.length !== other.recursivePathString.length) {

src/vs/workbench/contrib/chat/common/promptSyntax/languageFeatures/promptLinkDiagnosticsProvider.ts

@@ -25,16 +25,16 @@ import { IConfigurationService } from '../../../../../../platform/configuration/
 import { IMarkerData, IMarkerService, MarkerSeverity } from '../../../../../../platform/markers/common/markers.js';
 
 /**
- * TODO: @legomushroom
+ * Unique ID of the markers provider class.
  */
 const MARKERS_OWNER_ID = 'reusable-prompts-syntax';
 
 /**
- * TODO: @legomushroom
+ * Prompt links diagnostics provider for a single text model.
  */
 class PromptLinkDiagnosticsProvider extends ObservableDisposable {
 	/**
-	 * TODO: @legomushroom
+	 * Reference to the current prompt syntax parser instance.
 	 */
 	private readonly parser: TextModelPromptParser;
 
@@ -56,7 +56,7 @@ class PromptLinkDiagnosticsProvider extends ObservableDisposable {
 	}
 
 	/**
-	 * TODO: @legomushroom
+	 * Update diagnostic markers for the current editor.
 	 */
 	private async updateMarkers() {
 		// ensure that parsing process is settled
@@ -94,9 +94,14 @@ class PromptLinkDiagnosticsProvider extends ObservableDisposable {
 }
 
 /**
- * TODO: @legomushroom
+ * Convert a prompt link with an issue to a marker data.
+ *
+ * @throws
+ *  - if there is no link issue (e.g., `topError` undefined)
+ *  - if there is no link range to highlight (e.g., `linkRange` undefined)
+ *  - if the original error is of `NotPromptFile` type - we don't want to
+ *    show diagnostic markers for non-prompt file links in the prompts
  */
-// TODO: @legomushroom - add @throws info
 const toMarker = (
 	link: IPromptFileReference,
 ): IMarkerData => {
@@ -132,11 +137,12 @@ const toMarker = (
 };
 
 /**
- * TODO: @legomushroom
+ * The class that manages creation and disposal of {@link PromptLinkDiagnosticsProvider}
+ * classes for each specific editor text model.
  */
-export class PromptsLinkDiagnosticsProvider extends Disposable {
+export class PromptLinkDiagnosticsInstanceManager extends Disposable {
 	/**
-	 * TODO: @legomushroom
+	 * Currently available {@link PromptLinkDiagnosticsProvider} instances.
 	 */
 	private readonly providers: ObjectCache<PromptLinkDiagnosticsProvider, ITextModel>;
 
@@ -187,7 +193,7 @@ export class PromptsLinkDiagnosticsProvider extends Disposable {
 	}
 
 	/**
-	 * TODO: @legomushroom
+	 * Initialize a new {@link PromptLinkDiagnosticsProvider} for the given editor.
 	 */
 	private handleNewEditor(editor: IEditor): this {
 		const model = editor.getModel();
@@ -215,4 +221,4 @@ export class PromptsLinkDiagnosticsProvider extends Disposable {
 
 // register the provider as a workbench contribution
 Registry.as<IWorkbenchContributionsRegistry>(Extensions.Workbench)
-	.registerWorkbenchContribution(PromptsLinkDiagnosticsProvider, LifecyclePhase.Eventually);
+	.registerWorkbenchContribution(PromptLinkDiagnosticsInstanceManager, LifecyclePhase.Eventually);

src/vs/workbench/contrib/chat/common/promptSyntax/parsers/basePromptParser.ts

@@ -398,32 +398,18 @@ export abstract class BasePromptParser<T extends IPromptContentsProvider> extend
 	}
 
 	/**
-	 * TODO: @legomushroom
+	 * Get list of errors for the direct links of the current reference.
 	 */
 	public get errors(): readonly ResolveError[] {
-		// collect error conditions of direct child references
-		const childErrors = this
-			// get immediate references
-			.references
-			// filter out children without error conditions or
-			// the ones that are non-prompt snippet files
-			.filter((childReference) => {
-				const { errorCondition } = childReference;
-
-				return errorCondition && !(errorCondition instanceof NotPromptFile);
-			})
-			// map to error condition objects
-			.map((childReference): ResolveError => {
-				const { errorCondition } = childReference;
-
-				// `must` always be `true` because of the `filter` call above
-				assertDefined(
-					errorCondition,
-					`Error condition must be present for '${childReference.uri.path}'.`,
-				);
-
-				return errorCondition;
-			});
+		const childErrors: ResolveError[] = [];
+
+		for (const reference of this.references) {
+			const { errorCondition } = reference;
+
+			if (errorCondition && (!(errorCondition instanceof NotPromptFile))) {
+				childErrors.push(errorCondition);
+			}
+		}
 
 		return childErrors;
 	}

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

@@ -10,11 +10,11 @@ import { assertDefined } from '../../../../../../base/common/types.js';
 import { OpenFailed, RecursiveReference, FailedToResolveContentsStream } from '../../promptFileReferenceErrors.js';
 
 /**
- * TODO: @lego
+ * The top-most error of the reference tree.
  */
 export class TopError implements ITopError {
-	public readonly errorSubject = this.options.errorSubject;
 	public readonly originalError = this.options.originalError;
+	public readonly errorSubject = this.options.errorSubject;
 	public readonly errorsCount = this.options.errorsCount;
 	public readonly parentUri = this.options.parentUri;
 
@@ -24,7 +24,6 @@ export class TopError implements ITopError {
 
 
 	public get localizedMessage(): string {
-		// TODO: @legomushroom - update localization IDs
 		const { originalError, parentUri, errorSubject: subject, errorsCount } = this;
 
 		assert(
@@ -33,37 +32,37 @@ export class TopError implements ITopError {
 		);
 
 		// a note about how many more link issues are there
-		const moreIssuesNote = (errorsCount > 1)
-			? localize('chatPromptInstructionsBrokenReferenceSuffix222222', "\n(+{0} more issues)", errorsCount - 1)
+		const moreIssuesLabel = (errorsCount > 1)
+			? localize('workbench.reusable-prompts.top-error.more-issues-label', "\n(+{0} more issues)", errorsCount - 1)
 			: '';
 
 		if (subject === 'root') {
 			if (originalError instanceof OpenFailed) {
 				return localize(
-					'chatPromptInstructionsFileOpenFailed111',
+					'workbench.reusable-prompts.top-error.open-failed',
 					"Cannot open '{0}'.{1}",
 					originalError.uri.path,
-					moreIssuesNote,
+					moreIssuesLabel,
 				);
 			}
 
 			if (originalError instanceof FailedToResolveContentsStream) {
 				return localize(
-					'chatPromptInstructionsStreamOpenFailed1111',
+					'workbench.reusable-prompts.top-error.cannot-read',
 					"Cannot read '{0}'.{1}",
 					originalError.uri.path,
-					moreIssuesNote,
+					moreIssuesLabel,
 				);
 			}
 
 			if (originalError instanceof RecursiveReference) {
 				return localize(
-					'chatPromptInstructionsSelfRecursion4444',
+					'workbench.reusable-prompts.top-error.recursive-reference',
 					"Recursion to itself.",
 				);
 			}
 
-			return originalError.message + moreIssuesNote;
+			return originalError.message + moreIssuesLabel;
 		}
 
 		// a sanity check - because the error subject is not `root`, the parent must set
@@ -73,24 +72,27 @@ export class TopError implements ITopError {
 		);
 
 		const errorMessageStart = (subject === 'child')
-			? localize('chatPromptInstructionsBrokenReferenceFile', "Contains")
+			? localize(
+				'workbench.reusable-prompts.top-error.child.direct',
+				"Contains",
+			)
 			: localize(
-				'chatPromptInstructionsBrokenChildReference',
+				'workbench.reusable-prompts.top-error.child.indirect',
 				"Indirectly referenced prompt '{0}' contains",
 				parentUri.path,
 			);
 
 		const linkIssueName = (originalError instanceof RecursiveReference)
-			? localize('chatPromptInstructionsBrokenChildRecursiveLink', "recursive")
-			: localize('chatPromptInstructionsBrokenChildBrokenLink', "broken");
+			? localize('recursive', "recursive")
+			: localize('broken', "broken");
 
 		return localize(
-			'chatPromptInstructionsBrokenReference111',
+			'workbench.reusable-prompts.top-error.child.final-message',
 			"{0} a {1} link to '{2}' that will be ignored.{3}",
 			errorMessageStart,
 			linkIssueName,
 			originalError.uri.path,
-			moreIssuesNote,
+			moreIssuesLabel,
 		);
 	}
 }

src/vs/workbench/contrib/chat/common/promptSyntax/parsers/types.d.ts

@@ -9,7 +9,7 @@ import { IDisposable } from '../../../../../../base/common/lifecycle.js';
 import { IRange, Range } from '../../../../../../editor/common/core/range.js';
 
 /**
- * TODO: @legomushroom
+ * A resolve error with a parent prompt URI, if any.
  */
 export interface IResolveError {
 	/**
@@ -113,7 +113,7 @@ interface IPromptReferenceBase extends IDisposable {
 	readonly errorCondition: ResolveError | undefined;
 
 	/**
-	 * TODO: @legomushroom
+	 * Get list of errors for the direct links of the current reference.
 	 */
 	readonly errors: readonly ResolveError[];