Implement public facing StatementRangeSyntaxError (#11907)

Addresses #8350

- Requires posit-dev/ark#1040
- Blocks quarto-dev/quarto#919

Builds on:
- quarto-dev/quarto#914
- posit-dev/ark#1030

# Summary

This PR adds a new throwable `StatementRangeSyntaxError` to
`positron.d.ts`.

```ts
/**
 * An error thrown by a {@link StatementRangeProvider} to indicate that a statement range
 * cannot be provided due to a syntax error in the document.
 */
export class StatementRangeSyntaxError extends Error {
	/**
	 * Zero indexed line number where the syntax error occurred.
	 */
	readonly line?: number;

	/**
	 * Creates a new statement range syntax error.
	 *
	 * @param line Zero indexed line number where the syntax error occurred.
	 */
	constructor(line?: number);
}
```

This is the only public facing API change from this PR.

The idea is that from extension land (`positron-r`, `positron-python`,
and `quarto`) you should be able to throw a `StatementRangeSyntaxError`
from your `provideStatementRange()` provider, with an optional `line`
number of where the syntax error _roughly_ starts. This gets propagated
up through the main thread and into our `Cmd+Enter` handling in
`positronConsoleActions.ts`, where we now detect this special case and:
- Emit an info level notification telling the user that we can't execute
code due to a syntax error. If the `line` number is present, we give
them a button to jump to that line.
- Bail from `Cmd+Enter` handling altogether. We don't even do
one-line-at-a-time execution. #8350 has proved that this is just too
confusing when you are trying to execute code after a syntax error.

Here is what the end result looks like in an R script:


https://github.com/user-attachments/assets/23dca240-06af-40d5-8b1b-a8b24af99259

Note how you can execute R code _above_ the first syntax error, thanks
to posit-dev/ark#1030. It is only _below_ the
first syntax error that we emit this notification and refuse to execute.

It even works in roxygen2 comments where we have a little "subdocument":


https://github.com/user-attachments/assets/ec920753-400d-4493-b534-188dcf4e2a65

And lastly, it works in Quarto, where we have a "virtual document" for
R/Python and map the `line` number from that virtual document back into
the original Qmd, thanks to
quarto-dev/quarto#919 (note that if you try to
run that Quarto PR, you need to remove the version guard on Positron
2026.03.0 manually).

Additionally, quarto-dev/quarto#914 ensures that
you can use StatementRange in any syntax-error-free cell, even if some
other cell in the document has a syntax error.


https://github.com/user-attachments/assets/a01b9ed1-22fe-4169-b088-a8393800d9db

# Design

I considered many different designs along the way, but landed on a model
of:

- Extension host side _models errors as throwable errors_, i.e. with
`StatementRange` and `throw StatementRangeSyntaxError`

  ```ts
  export interface StatementRange {
    readonly range: vscode.Range;
    readonly code?: string;
  }

  export class StatementRangeSyntaxError extends Error {
    readonly line?: number;
    constructor(line?: number);
  }
  ```

- Main thread side _models errors as data_, i.e. a single
`IStatementRange` type made up as:

  ```ts
type IStatementRange = IStatementRangeSuccess | IStatementRangeRejection

  type IStatementRangeRejection = IStatementRangeSyntaxRejection

  export interface IStatementRangeSuccess {
    readonly kind: StatementRangeKind.Success;
    readonly range: IRange;
    readonly code?: string;
  }

  export interface IStatementRangeSyntaxRejection {
    readonly kind: StatementRangeKind.Rejection;
    readonly rejectionKind: StatementRangeRejectionKind.Syntax;
    readonly line?: number;
  }
  ```

Some rationale:

- Backwards compatible and public facing `StatementRange` doesn't change

- Can add new error/rejection variants as needed

- Can't easily model main thread side errors as, well, `Error`s, because
the `StatementRangeSyntaxError` doesn't serialize across the extension
-> main thread boundary well. You basically have to turn it into some
"data" type anyways to do this, and then it doesn't feel worth it to
convert back on the main thread side.

- Ark's custom `StatementRange` LSP Request also now uses the "success"
vs "rejection" model. From Ark's LSP-ish perspective, a "rejection" is
an allowed value that can be returned as an LSP Response. We reserve the
JSONRPC error path for true "holy crap something horrible happened and I
can't complete this request" cases.

The end result looks like this:

<img width="5127" height="4470" alt="test"
src="https://github.com/user-attachments/assets/b341c1dd-edac-45a2-9aed-03a4b05b3c01"
/>

# Prior art

There isn't much prior art for exactly what I'm trying to do here, but
there is a little bit:

- `FileSystemError` with its various flavors. Not quite the same as us
because none of the flavors have any metadata to pass through, like
`line`. That metadata is what steered me away from trying to have one
overarching `StatementRangeError` class that could contain something
like `static SyntaxError(line?: number): StatementRangeError`. I did try
this, but the boilerplate didn't feel worth it.


https://github.com/posit-dev/positron/blob/31c0111d42eaff76f06e1800836663e5765e1df1/src/vscode-dts/vscode.d.ts#L9474-L9486

- `Rejection`, which is used by the `RenameProvider`. Catches an error
from the LSP side of things and converts it into a `Rejection` "data"
type, kind of like we do. Strangely does `RenameProvider & Rejection` as
the return value type.
 
- Defined here
https://github.com/posit-dev/positron/blob/9754ca9e56524315fa6b2d1981fb6cb82ef5cd7b/src/vs/editor/common/languages.ts#L2127-L2138
- Catching the error here
https://github.com/posit-dev/positron/blob/9754ca9e56524315fa6b2d1981fb6cb82ef5cd7b/src/vs/workbench/api/common/extHostLanguageFeatures.ts#L882-L903

# QA

### Release Notes

#### New Features

- Stepping through code with `Cmd + Enter` now works more reliably when
there are syntax errors in the document:
    - For R code:
- [Code _above_ the first syntax
error](posit-dev/ark#1030) can now be executed
reliably with `Cmd + Enter`
- [Code _below_ the first syntax
error](#11907) causes a
notification to pop up that informs you that reliable execution is
impossible and provides you with a button to jump to the syntax error
- For Quarto documents, a syntax error in one chunk no longer affects
the ability to [run code in other
chunks](quarto-dev/quarto#914)

### QA Notes

QA: It would be nice to have two integration tests

```r
1 
  + 1 # <put cursor here and execute this, it should work now and send the whole statement>

2 + \ 2
```

```r
1 + \ 1

2 
  + 2 # <put cursor here and execute this, it should not send anything, and a notification should pop up>
```

`@:ark` `@:quarto` `@:console`

---------

Signed-off-by: Davis Vaughan <davis@posit.co>
Co-authored-by: Lionel Henry <lionel.hry@proton.me>

Author: DavisVaughan

extensions/positron-r/package.json

@@ -1078,7 +1078,7 @@
   },
   "positron": {
     "binaryDependencies": {
-      "ark": "0.1.227"
+      "ark": "0.1.229"
     },
     "minimumRVersion": "4.2.0",
     "minimumRenvVersion": "1.0.9"

extensions/positron-r/src/statement-range.ts

@@ -5,16 +5,36 @@
 
 import * as positron from 'positron';
 import * as vscode from 'vscode';
-import { CancellationToken, LanguageClient, Position, Range, RequestType, VersionedTextDocumentIdentifier } from 'vscode-languageclient/node';
+import { LanguageClient, Position, Range, RequestType, VersionedTextDocumentIdentifier } from 'vscode-languageclient/node';
+
+enum StatementRangeKind {
+	Success = 'success',
+	Rejection = 'rejection'
+}
+
+enum StatementRangeRejectionKind {
+	Syntax = 'syntax'
+}
 
 interface StatementRangeParams {
 	textDocument: VersionedTextDocumentIdentifier;
 	position: Position;
 }
 
-interface StatementRangeResponse {
-	range: Range;
-	code?: string;
+type StatementRangeResponse = StatementRangeSuccess | StatementRangeRejection;
+
+interface StatementRangeSuccess {
+	readonly kind: StatementRangeKind.Success;
+	readonly range: Range;
+	readonly code?: string;
+}
+
+type StatementRangeRejection = StatementRangeSyntaxRejection;
+
+interface StatementRangeSyntaxRejection {
+	readonly kind: StatementRangeKind.Rejection;
+	readonly rejectionKind: StatementRangeRejectionKind.Syntax;
+	readonly line?: number;
 }
 
 export namespace StatementRangeRequest {
@@ -38,23 +58,41 @@ export class RStatementRangeProvider implements positron.StatementRangeProvider
 	async provideStatementRange(
 		document: vscode.TextDocument,
 		position: vscode.Position,
-		token: vscode.CancellationToken): Promise<positron.StatementRange | undefined> {
+		token: vscode.CancellationToken
+	): Promise<positron.StatementRange | undefined> {
 
 		const params: StatementRangeParams = {
 			textDocument: this._client.code2ProtocolConverter.asVersionedTextDocumentIdentifier(document),
 			position: this._client.code2ProtocolConverter.asPosition(position)
 		};
 
-		const response = this._client.sendRequest(StatementRangeRequest.type, params, token);
+		const data = await this._client.sendRequest(StatementRangeRequest.type, params, token);
+
+		if (!data) {
+			return undefined;
+		}
 
-		return response.then(data => {
-			if (!data) {
-				return undefined;
+		switch (data.kind) {
+			case StatementRangeKind.Success: {
+				return {
+					range: this._client.protocol2CodeConverter.asRange(data.range),
+					// Explicitly normalize non-strings to `undefined` (i.e. a possible `null`)
+					code: typeof data.code === 'string' ? data.code : undefined
+				} satisfies positron.StatementRange;
+			}
+			case StatementRangeKind.Rejection: {
+				switch (data.rejectionKind) {
+					case StatementRangeRejectionKind.Syntax: {
+						throw new positron.StatementRangeSyntaxError(data.line);
+					}
+					default: {
+						throw new Error(`Unrecognized 'StatementRangeRejectionKind': ${data.rejectionKind}`);
+					}
+				}
+			}
+			default: {
+				throw new Error(`Unrecognized 'StatementRangeKind': ${data}`);
 			}
-			const range = this._client.protocol2CodeConverter.asRange(data.range);
-			// Explicitly normalize non-strings to `undefined` (i.e. a possible `null`)
-			const code = typeof data.code === 'string' ? data.code : undefined;
-			return { range: range, code: code } as positron.StatementRange;
-		});
+		}
 	}
 }

extensions/positron-r/src/test/statement-range.test.ts

@@ -0,0 +1,163 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (C) 2026 Posit Software, PBC. All rights reserved.
+ *  Licensed under the Elastic License 2.0. See LICENSE.txt for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import './mocha-setup';
+
+import * as assert from 'assert';
+import * as positron from 'positron';
+import * as vscode from 'vscode';
+import * as testKit from './kit';
+import { createRandomFile, deleteFile } from './editor-utils';
+
+suite('RStatementRangeProvider', () => {
+	let sessionDisposable: vscode.Disposable;
+
+	suiteSetup(async function () {
+		const [, disposable] = await testKit.startR();
+		sessionDisposable = disposable;
+	});
+
+	suiteTeardown(async () => {
+		await sessionDisposable?.dispose();
+	});
+
+	test('single-line expression', async function () {
+		const code = `
+1 + 1
+`.trimStart();
+
+		await testKit.withDisposables(async (disposables) => {
+			const result = await getStatementRange(
+				disposables,
+				code,
+				new vscode.Position(0, 0)
+			);
+			assert.ok(result, 'Expected a statement range result');
+			assert.strictEqual(result.range.start.line, 0);
+			assert.strictEqual(result.range.start.character, 0);
+			assert.strictEqual(result.range.end.line, 0);
+			assert.strictEqual(result.range.end.character, 5);
+		});
+	});
+
+	test('multi-line block from first line', async function () {
+		const code = `
+for (i in 1:3) {
+	print(i)
+}
+`.trimStart();
+
+		await testKit.withDisposables(async (disposables) => {
+			const result = await getStatementRange(
+				disposables,
+				code,
+				new vscode.Position(0, 0)
+			);
+
+			assert.ok(result, 'Expected a statement range result');
+			assert.strictEqual(result.range.start.line, 0);
+			assert.strictEqual(result.range.start.character, 0);
+			assert.strictEqual(result.range.end.line, 2);
+			assert.strictEqual(result.range.end.character, 1);
+		});
+	});
+
+	test('in a pipe chain', async function () {
+		const code = `
+1 + 1
+
+df |>
+	mutate(y = x + 1) |>
+	mutate(z = x + y)
+`.trimStart();
+
+		await testKit.withDisposables(async (disposables) => {
+			const result = await getStatementRange(
+				disposables,
+				code,
+				new vscode.Position(3, 3)
+			);
+
+			assert.ok(result, 'Expected a statement range result');
+			assert.strictEqual(result.range.start.line, 2);
+			assert.strictEqual(result.range.start.character, 0);
+			assert.strictEqual(result.range.end.line, 4);
+			assert.strictEqual(result.range.end.character, 18);
+		});
+	});
+
+	test('cursor before syntax error works fine', async function () {
+		const code = `
+df |>
+	summarise(foo = mean(x))
+
+df |>
+	mutate(y = x \ 1 |>
+	mutate(z = x + y)
+`.trimStart();
+
+		await testKit.withDisposables(async (disposables) => {
+			const result = await getStatementRange(
+				disposables,
+				code,
+				new vscode.Position(1, 3)
+			);
+
+			assert.ok(result, 'Expected a statement range result');
+			assert.strictEqual(result.range.start.line, 0);
+			assert.strictEqual(result.range.start.character, 0);
+			assert.strictEqual(result.range.end.line, 1);
+			assert.strictEqual(result.range.end.character, 25);
+		});
+	});
+
+	test('cursor in syntax error throws StatementRangeSyntaxError', async function () {
+		const code = `
+df |>
+	summarise(foo = mean(x))
+
+df |>
+	mutate(y = x \ 1 |>
+	mutate(z = x + y)
+`.trimStart();
+
+		await testKit.withDisposables(async (disposables) => {
+			await assert.rejects(
+				() => getStatementRange(
+					disposables,
+					code,
+					new vscode.Position(4, 0)
+				),
+				(err) => {
+					assert.ok(err instanceof positron.StatementRangeSyntaxError);
+					assert.strictEqual(err.line, 3);
+					return true;
+				}
+			);
+		});
+	});
+});
+
+/**
+ * Executes the statement range provider for an R file with the given contents
+ * at the given position.
+ */
+async function getStatementRange(
+	disposables: vscode.Disposable[],
+	contents: string,
+	position: vscode.Position
+): Promise<positron.StatementRange | undefined> {
+	const fileUri = await createRandomFile(contents, 'R');
+	disposables.push({ dispose: () => deleteFile(fileUri) });
+
+	const doc = await vscode.workspace.openTextDocument(fileUri);
+	await vscode.window.showTextDocument(doc);
+
+	return await vscode.commands.executeCommand<positron.StatementRange | undefined>(
+		'vscode.executeStatementRangeProvider',
+		doc.uri,
+		position
+	);
+}

src/positron-dts/positron.d.ts

@@ -1542,6 +1542,9 @@ declare module 'positron' {
 		 * cursor is within. If the cursor is not within a statement, return the
 		 * range of the next statement, if one exists.
 		 *
+		 * Throw a {@link StatementRangeSyntaxError} to indicate that a statement range
+		 * cannot be provided due to a syntax error in the document.
+		 *
 		 * @param document The document in which the command was invoked.
 		 * @param position The position at which the command was invoked.
 		 * @param token A cancellation token.
@@ -1565,7 +1568,24 @@ declare module 'positron' {
 		 * The code for this statement range, if different from the document contents at this range.
 		 */
 		readonly code?: string;
+	}
+
+	/**
+	 * An error thrown by a {@link StatementRangeProvider} to indicate that a statement range
+	 * cannot be provided due to a syntax error in the document.
+	 */
+	export class StatementRangeSyntaxError extends Error {
+		/**
+		 * Zero indexed line number where the syntax error occurred.
+		 */
+		readonly line?: number;
 
+		/**
+		 * Creates a new statement range syntax error.
+		 *
+		 * @param line Zero indexed line number where the syntax error occurred.
+		 */
+		constructor(line?: number);
 	}
 
 	export interface HelpTopicProvider {

src/vs/editor/common/languages.ts

@@ -2040,6 +2040,15 @@ export class FoldingRangeKind {
 }
 
 // --- Start Positron ---
+export const enum StatementRangeKind {
+	Success = 'success',
+	Rejection = 'rejection',
+}
+
+export const enum StatementRangeRejectionKind {
+	Syntax = 'syntax',
+}
+
 export interface StatementRangeProvider {
 	/**
 	 * Provide the statement that contains the given position.
@@ -2048,10 +2057,19 @@ export interface StatementRangeProvider {
 		ProviderResult<IStatementRange>;
 }
 
+export type IStatementRange = IStatementRangeSuccess | IStatementRangeRejection;
+
+export type IStatementRangeRejection = IStatementRangeSyntaxRejection;
+
 /**
  * The range of a statement, plus optionally the code for the range.
  */
-export interface IStatementRange {
+export interface IStatementRangeSuccess {
+	/**
+	 * The kind of statement range result.
+	 */
+	readonly kind: StatementRangeKind.Success;
+
 	/**
 	 * The range of the statement at the given position.
 	 */
@@ -2061,7 +2079,23 @@ export interface IStatementRange {
 	 * The code for this statement range, if different from the document contents at this range.
 	 */
 	readonly code?: string;
+}
 
+export interface IStatementRangeSyntaxRejection {
+	/**
+	 * The kind of statement range result.
+	 */
+	readonly kind: StatementRangeKind.Rejection;
+
+	/**
+	 * The kind of rejection.
+	 */
+	readonly rejectionKind: StatementRangeRejectionKind.Syntax;
+
+	/**
+	 * Zero indexed line number where the syntax error occurred.
+	 */
+	readonly line?: number;
 }
 
 export interface HelpTopicProvider {

src/vs/editor/common/standalone/standaloneEnums.ts

@@ -881,6 +881,15 @@ export enum SignatureHelpTriggerKind {
 	ContentChange = 3
 }
 
+export enum StatementRangeKind {
+	Success = 'success',
+	Rejection = 'rejection'
+}
+
+export enum StatementRangeRejectionKind {
+	Syntax = 'syntax'
+}
+
 /**
  * A symbol kind.
  */

src/vs/editor/contrib/positronStatementRange/browser/provideStatementRange.ts

@@ -16,7 +16,7 @@ import { IModelService } from '../../../common/services/model.js';
 import { CancellationToken } from '../../../../base/common/cancellation.js';
 
 
-async function provideStatementRange(
+export async function provideStatementRange(
 	registry: LanguageFeatureRegistry<languages.StatementRangeProvider>,
 	model: ITextModel,
 	position: Position,