From d599f959e267c54ded9a4867ac0f2b9f9b805ddf Mon Sep 17 00:00:00 2001
From: Julia Silge <julia.silge@gmail.com>
Date: Thu, 7 Nov 2024 15:22:06 -0700
Subject: [PATCH] Add new `positron.executeHelpTopicProvider` API command
 (#5292)

Addresses #4097

Goes together with https://github.com/quarto-dev/quarto/pull/599; the
Quarto PR is needed to actually see this work but this PR should be able
to be merged on its own.

### QA Notes

In a Quarto file, you should be able to use <kbd>F1</kbd> to bring up
help for R like so:


![help-quarto](https://github.com/user-attachments/assets/e23c6a23-f0c5-404e-8284-1274c7c66b8b)

This is only working right now for R, because of
https://github.com/posit-dev/positron/issues/5290. When we fix that, we
should also confirm it works in a `.qmd` as well.
---
 .../positronHelp/browser/provideHelpTopic.ts  | 57 +++++++++++++++++++
 src/vs/editor/editor.all.ts                   |  1 +
 .../api/common/extHostApiCommands.ts          |  8 +++
 3 files changed, 66 insertions(+)
 create mode 100644 src/vs/editor/contrib/positronHelp/browser/provideHelpTopic.ts

diff --git a/src/vs/editor/contrib/positronHelp/browser/provideHelpTopic.ts b/src/vs/editor/contrib/positronHelp/browser/provideHelpTopic.ts
new file mode 100644
index 00000000000..094ad3529c2
--- /dev/null
+++ b/src/vs/editor/contrib/positronHelp/browser/provideHelpTopic.ts
@@ -0,0 +1,57 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (C) 2024 Posit Software, PBC. All rights reserved.
+ *  Licensed under the Elastic License 2.0. See LICENSE.txt for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { LanguageFeatureRegistry } from 'vs/editor/common/languageFeatureRegistry';
+import { ILanguageFeaturesService } from 'vs/editor/common/services/languageFeatures';
+import * as languages from 'vs/editor/common/languages';
+import { onUnexpectedExternalError } from 'vs/base/common/errors';
+import { CommandsRegistry } from 'vs/platform/commands/common/commands';
+import { assertType } from 'vs/base/common/types';
+import { URI } from 'vs/base/common/uri';
+import { IPosition, Position } from 'vs/editor/common/core/position';
+import { ITextModel } from 'vs/editor/common/model';
+import { IModelService } from 'vs/editor/common/services/model';
+import { CancellationToken } from 'vs/base/common/cancellation';
+
+
+async function provideHelpTopic(
+	registry: LanguageFeatureRegistry<languages.HelpTopicProvider>,
+	model: ITextModel,
+	position: Position,
+	token: CancellationToken
+): Promise<string | undefined> {
+
+	const providers = registry.ordered(model);
+
+	for (const provider of providers) {
+		try {
+			const result = await provider.provideHelpTopic(model, position, token);
+			if (result) {
+				return result;
+			}
+		} catch (err) {
+			onUnexpectedExternalError(err);
+		}
+	}
+	return undefined;
+}
+
+CommandsRegistry.registerCommand('_executeHelpTopicProvider', async (accessor, ...args: [URI, IPosition]) => {
+	const [uri, position] = args;
+	assertType(URI.isUri(uri));
+	assertType(Position.isIPosition(position));
+
+	const model = accessor.get(IModelService).getModel(uri);
+	if (!model) {
+		return undefined;
+	}
+	const languageFeaturesService = accessor.get(ILanguageFeaturesService);
+	return await provideHelpTopic(
+		languageFeaturesService.helpTopicProvider,
+		model,
+		Position.lift(position),
+		CancellationToken.None
+	);
+});
diff --git a/src/vs/editor/editor.all.ts b/src/vs/editor/editor.all.ts
index b8650497f32..9b9e93ef729 100644
--- a/src/vs/editor/editor.all.ts
+++ b/src/vs/editor/editor.all.ts
@@ -67,6 +67,7 @@ import 'vs/editor/contrib/diffEditorBreadcrumbs/browser/contribution';
 // --- Start Positron ---
 import 'vs/editor/contrib/positronEditorActions/browser/positronEditorActions';
 import 'vs/editor/contrib/positronStatementRange/browser/provideStatementRange';
+import 'vs/editor/contrib/positronHelp/browser/provideHelpTopic';
 // --- End Positron ---
 
 // Load up these strings even in VSCode, even if they are not used
diff --git a/src/vs/workbench/api/common/extHostApiCommands.ts b/src/vs/workbench/api/common/extHostApiCommands.ts
index 7ef5e410fe4..03c8e52d1ab 100644
--- a/src/vs/workbench/api/common/extHostApiCommands.ts
+++ b/src/vs/workbench/api/common/extHostApiCommands.ts
@@ -527,6 +527,14 @@ const newCommands: ApiCommand[] = [
 			return { range: typeConverters.Range.to(result.range), code: result.code };
 		})
 	),
+	// -- show help topic
+	new ApiCommand(
+		'positron.executeHelpTopicProvider', '_executeHelpTopicProvider', 'Execute help topic provider.',
+		[ApiCommandArgument.Uri, ApiCommandArgument.Position],
+		new ApiCommandResult<string | null>('A promise that resolves to a string.', result => {
+			return result;
+		})
+	),
 	// --- End Positron
 
 	// --- context keys