Add new command for positron.executeCodeInConsole to be used by extensions that handles uri, position, next position (#10580)

- Addresses #7709
- Related to quarto-dev/quarto#867

I've been collaborating with @vezwork on how to get more language
features hooked up in Quarto's visual editor, and we think this is what
we need for the Quarto custom editor interface to be able to send code
statement-by-statement to the console. Over in the Quarto extension, we
can now do something like:

```typescript
  const nextPosition = await vscode.commands.executeCommand(
      'positron.executeCodeInConsole',
      'python',                              // language ID
      vscode.Uri.file('/path/to/script.py'), // document URI
      new vscode.Position(5, 0)              // position
  ) as vscode.Position | undefined;

```

What we get back is the next position to move the cursor to, in Quarto's
case for the virtual doc underlying the visual editor.

It's a little weird to now have two commands, both the old
`workbench.action.positronConsole.executeCode` and the new
`positron.executeCodeInConsole`, but now that we're dealing with
positions (and less so, URIs) we need to use the converters that we have
access to in `src/vs/workbench/api/common/extHostApiCommands.ts`. I
think I'd argue they do different enough things that this is OK?
Although you can now technically call
`workbench.action.positronConsole.executeCode` with a uri and position,
but they would have to be the _internal_ main process versions of those;
this feels somewhat weird. Is it worth doing more refactoring here to
make this nicer?

@:sessions
@:console

### Release Notes

#### New Features

- Added new command `positron.executeCodeInConsole` for extensions to
execute code for a given language, URI, and position (such as for the
Quarto visual editor)

#### Bug Fixes

- N/A


### QA Notes

Once we get changes merged on both the Positron and Quarto sides, you
should be able to execute multi-line statements in the console from the
visual editor. Once we get further along, I can share more detailed
examples

Author: juliasilge

src/vs/workbench/api/common/extHostApiCommands.ts

@@ -557,6 +557,18 @@ const newCommands: ApiCommand[] = [
 			return result;
 		})
 	),
+	// -- execute code in console
+	new ApiCommand(
+		'positron.executeCodeFromPosition', '_executeCodeInConsole', 'Execute code in the Positron console.',
+		[
+			ApiCommandArgument.String.with('languageId', 'The language ID of the code to execute'),
+			ApiCommandArgument.Uri.with('uri', 'The URI of the document to execute code from'),
+			ApiCommandArgument.Position.with('position', 'The position in the document to execute code from')
+		],
+		new ApiCommandResult<IPosition | undefined, types.Position | undefined>('A promise that resolves to the next position after executing the code.', result => {
+			return result ? typeConverters.Position.to(result) : undefined;
+		})
+	),
 	// --- End Positron
 
 	// --- context keys

src/vs/workbench/contrib/positronConsole/browser/positronConsoleActions.ts

@@ -4,13 +4,15 @@
  *--------------------------------------------------------------------------------------------*/
 
 import { localize } from '../../../../nls.js';
-import { isString } from '../../../../base/common/types.js';
+import { URI } from '../../../../base/common/uri.js';
+import { isString, assertType } from '../../../../base/common/types.js';
 import { Codicon } from '../../../../base/common/codicons.js';
 import { ITextModel } from '../../../../editor/common/model.js';
 import { IRange } from '../../../../editor/common/core/range.js';
 import { IEditor } from '../../../../editor/common/editorCommon.js';
 import { ILogService } from '../../../../platform/log/common/log.js';
-import { Position } from '../../../../editor/common/core/position.js';
+import { IModelService } from '../../../../editor/common/services/model.js';
+import { IPosition, Position } from '../../../../editor/common/core/position.js';
 import { CancellationToken } from '../../../../base/common/cancellation.js';
 import { KeyChord, KeyCode, KeyMod } from '../../../../base/common/keyCodes.js';
 import { ILocalizedString } from '../../../../platform/action/common/action.js';
@@ -32,7 +34,7 @@ import { IPositronModalDialogsService } from '../../../services/positronModalDia
 import { IPositronConsoleService, POSITRON_CONSOLE_VIEW_ID } from '../../../services/positronConsole/browser/interfaces/positronConsoleService.js';
 import { IExecutionHistoryService } from '../../../services/positronHistory/common/executionHistoryService.js';
 import { CodeAttributionSource, IConsoleCodeAttribution } from '../../../services/positronConsole/common/positronConsoleCodeExecution.js';
-import { ICommandService } from '../../../../platform/commands/common/commands.js';
+import { CommandsRegistry, ICommandService } from '../../../../platform/commands/common/commands.js';
 import { POSITRON_NOTEBOOK_CELL_EDITOR_FOCUSED } from '../../positronNotebook/browser/ContextKeysManager.js';
 import { getContextFromActiveEditor } from '../../notebook/browser/controller/coreActions.js';
 
@@ -315,6 +317,8 @@ export function registerPositronConsoleActions() {
 		 *   - advance: Optionally, if the cursor should be advanced to the next statement. If `undefined`, fallbacks to `true`.
 		 *   - mode: Optionally, the code execution mode for a language runtime. If `undefined` fallbacks to `Interactive`.
 		 *   - errorBehavior: Optionally, the error behavior for a language runtime. If `undefined` fallbacks to `Continue`.
+		 *   - uri: The URI of the document to execute code from. Must be provided together with `position`.
+		 *   - position: The position in the document to execute code from. Must be provided together with `uri`.
 		 */
 		async run(
 			accessor: ServicesAccessor,
@@ -324,13 +328,17 @@ export function registerPositronConsoleActions() {
 				advance?: boolean;
 				mode?: RuntimeCodeExecutionMode;
 				errorBehavior?: RuntimeErrorBehavior;
-			} = {}
-		) {
+			} & (
+					| { uri: URI; position: Position }
+					| { uri?: never; position?: never }
+				) = {}
+		): Promise<Position | undefined> {
 			// Access services.
 			const editorService = accessor.get(IEditorService);
 			const languageFeaturesService = accessor.get(ILanguageFeaturesService);
 			const languageService = accessor.get(ILanguageService);
 			const logService = accessor.get(ILogService);
+			const modelService = accessor.get(IModelService);
 			const notificationService = accessor.get(INotificationService);
 			const positronConsoleService = accessor.get(IPositronConsoleService);
 
@@ -340,15 +348,44 @@ export function registerPositronConsoleActions() {
 			// The code to execute.
 			let code: string | undefined = undefined;
 
-			// If there is no active editor, there is nothing to execute.
-			const editor = editorService.activeTextEditorControl as IEditor;
-			if (!editor) {
-				return;
+			// Determine if we're using a provided URI or the active editor
+			let editor: IEditor | undefined;
+			let model: ITextModel | undefined;
+			let position: Position;
+			let nextPosition: Position | undefined;
+
+			if (opts.uri) {
+				// Use the provided URI to get the model
+				const foundModel = modelService.getModel(opts.uri);
+				if (!foundModel) {
+					notificationService.notify({
+						severity: Severity.Info,
+						message: localize('positron.executeCode.noModel', "Cannot execute code. Unable to find document at {0}.", opts.uri.toString()),
+						sticky: false
+					});
+					return;
+				}
+				model = foundModel;
+				// Use the provided position (guaranteed to exist when uri is provided)
+				position = opts.position;
+				// No editor context when URI is provided
+				editor = undefined;
+			} else {
+				// Use the active editor
+				editor = editorService.activeTextEditorControl as IEditor;
+				if (!editor) {
+					return;
+				}
+				model = editor.getModel() as ITextModel;
+				const editorPosition = editor.getPosition();
+				if (!editorPosition) {
+					return;
+				}
+				position = editorPosition;
 			}
 
 			// Get the code to execute.
-			const selection = editor.getSelection();
-			const model = editor.getModel() as ITextModel;
+			const selection = editor?.getSelection();
 
 			// If we have a selection and it isn't empty, then we use its contents (even if it
 			// only contains whitespace or comments) and also retain the user's selection location.
@@ -367,13 +404,6 @@ export function registerPositronConsoleActions() {
 				// HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK
 			}
 
-			// Get the position of the cursor. If we don't have a selection, we'll use this to
-			// determine the code to execute.
-			const position = editor.getPosition();
-			if (!position) {
-				return;
-			}
-
 			// Get all the statement range providers for the active document.
 			const statementRangeProviders =
 				languageFeaturesService.statementRangeProvider.all(model);
@@ -401,7 +431,7 @@ export function registerPositronConsoleActions() {
 					code = isString(statementRange.code) ? statementRange.code : model.getValueInRange(statementRange.range);
 
 					if (advance) {
-						await this.advanceStatement(model, editor, statementRange, statementRangeProviders[0], logService);
+						nextPosition = await this.advanceStatement(model, editor, statementRange, statementRangeProviders[0], logService);
 					}
 				} else {
 					// The statement range provider didn't return a range. This
@@ -412,8 +442,7 @@ export function registerPositronConsoleActions() {
 			// If no selection was found, use the contents of the line containing the cursor
 			// position.
 			if (!isString(code)) {
-				const position = editor.getPosition();
-				let lineNumber = position?.lineNumber ?? 0;
+				let lineNumber = position.lineNumber;
 
 				if (lineNumber > 0) {
 					// Find the first non-empty line after the cursor position and read the
@@ -431,21 +460,23 @@ export function registerPositronConsoleActions() {
 
 				// If we have code and a position move the cursor to the next line with code on it,
 				// or just to the next line if all additional lines are blank.
-				if (advance && isString(code) && position) {
-					this.advanceLine(model, editor, position, lineNumber, code, editorService);
+				if (advance && isString(code)) {
+					nextPosition = this.advanceLine(model, editor, position, lineNumber, code, editorService);
 				}
 
-				if (!isString(code) && position && lineNumber === model.getLineCount()) {
+				if (!isString(code) && lineNumber === model.getLineCount()) {
 					// If we still don't have code and we are at the end of the document, add a
 					// newline to the end of the document.
 					this.amendNewlineToEnd(model);
 
 					// We don't move to that new line to avoid adding a bunch of empty
 					// lines to the end. The edit operation typically moves us to the new line,
 					// so we have to undo that.
-					const newPosition = new Position(lineNumber, 1);
-					editor.setPosition(newPosition);
-					editor.revealPositionInCenterIfOutsideViewport(newPosition);
+					if (editor) {
+						const newPosition = new Position(lineNumber, 1);
+						editor.setPosition(newPosition);
+						editor.revealPositionInCenterIfOutsideViewport(newPosition);
+					}
 				}
 
 				// If we still don't have code after looking at the cursor position,
@@ -472,18 +503,18 @@ export function registerPositronConsoleActions() {
 					mode: opts.mode,
 					errorBehavior: opts.errorBehavior
 				});
+			return nextPosition;
 		}
 
 		async advanceStatement(
 			model: ITextModel,
-			editor: IEditor,
+			editor: IEditor | undefined,
 			statementRange: IStatementRange,
 			provider: StatementRangeProvider,
 			logService: ILogService,
-		) {
+		): Promise<Position> {
 
-			// Move the cursor to the next
-			// statement by creating a position on the line
+			// Calculate the next position by creating a position on the line
 			// following the statement and then invoking the
 			// statement range provider again to find the appropriate
 			// boundary of the next statement.
@@ -505,8 +536,6 @@ export function registerPositronConsoleActions() {
 					model.getLineCount(),
 					1
 				);
-				editor.setPosition(newPosition);
-				editor.revealPositionInCenterIfOutsideViewport(newPosition);
 			} else {
 				// Invoke the statement range provider again to
 				// find the appropriate boundary of the next statement.
@@ -548,20 +577,24 @@ export function registerPositronConsoleActions() {
 						);
 					}
 				}
+			}
 
+			// Only move the cursor if we have an editor
+			if (editor) {
 				editor.setPosition(newPosition);
 				editor.revealPositionInCenterIfOutsideViewport(newPosition);
 			}
+			return newPosition;
 		}
 
 		advanceLine(
 			model: ITextModel,
-			editor: IEditor,
+			editor: IEditor | undefined,
 			position: Position,
 			lineNumber: number,
 			code: string,
 			editorService: IEditorService,
-		) {
+		): Position {
 			// HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK HACK
 			// This attempts to address https://github.com/posit-dev/positron/issues/1177
 			// by tacking a newline onto indented Python code fragments that end at an empty
@@ -598,8 +631,12 @@ export function registerPositronConsoleActions() {
 			}
 
 			const newPosition = position.with(lineNumber, 0);
-			editor.setPosition(newPosition);
-			editor.revealPositionInCenterIfOutsideViewport(newPosition);
+			// Only move the cursor if we have an editor
+			if (editor) {
+				editor.setPosition(newPosition);
+				editor.revealPositionInCenterIfOutsideViewport(newPosition);
+			}
+			return newPosition;
 		}
 
 		amendNewlineToEnd(model: ITextModel) {
@@ -1062,3 +1099,22 @@ export function registerPositronConsoleActions() {
 		}
 	});
 }
+
+
+/**
+ * Register the internal command for executing code in console from the extension API.
+ * This command is called by the positron.executeCodeInConsole API command.
+ */
+CommandsRegistry.registerCommand('_executeCodeInConsole', async (accessor, ...args: [string, URI, IPosition]) => {
+	const [languageId, uri, position] = args;
+	assertType(typeof languageId === 'string');
+	assertType(URI.isUri(uri));
+	assertType(Position.isIPosition(position));
+
+	const commandService = accessor.get(ICommandService);
+	return await commandService.executeCommand('workbench.action.positronConsole.executeCode', {
+		languageId,
+		uri,
+		position: Position.lift(position)
+	});
+});