Consider to surface debug URIs in the API

[weinand]

@pavelfeldman what is the exact use case?
Why is regular VS Code API for opening files and revealing some line not sufficient?

[pavelfeldman]

User case 1

• Open Chrome DevTools on this page
• In console, evaluate function foo() {}
• Followed by inspect(foo)
• Observe function revealed

What happens here is adapter requests that certain debugging location is revealed, it does not necessarily have associated path in the workspace.

User case 2

• Open Chrome DevTools on this page
• Press Ctrl+P and navigate to the frameworks-e1e8de5c.js
• In the lower left corder of the source editor, click the {} button
• Observe a new debugger location that does not have an associated workspace path revealed

Should VS Code extension decide to implement similar functionality, it would need to reveal the resulting pretty-printed script.

[pavelfeldman]

@weinand ^^

[dgozman]

Related issue:

1. Open this folder.
2. Run "Launch Program".
3. Ctrl+Shit+P, "Debug: Open Loaded Script", type index.js, hit Enter.
4. Nothing happens, debugging VSCode shows the following error:

Error: cannot open debug:/Users/dgozman/code/vscode-pwa/demos/node-ts/out/index.js?session%3D1208fa0a-83dc-4a6e-a83d-4c142a628f2a. Detail: [UriError]: Scheme is missing: {scheme: "", authority: "", path: "/Users/dgozman/code/vscode-pwa/demos/node-ts/out/index.js", query: "", fragment: ""}

Debugged down to this line.

[weinand]

Internally VS Code uses debug uris to refer to DAP provided sources. Debug uris have this format:

/**
 * Debug URI format
 *
 * a debug URI represents a Source object and the debug session where the Source comes from.
 *
 *       debug:arbitrary_path?session=123e4567-e89b-12d3-a456-426655440000&ref=1016
 *       \___/ \____________/ \__________________________________________/ \______/
 *         |          |                             |                          |
 *      scheme   source.path                    session id            source.reference
 */

Today's problem:

By using VS Code's internal knowledge about debug Uris, it is possible to construct a debug uri based on a DAP Source object. Please note that the "Source" structure is a DAP concept that is not surfaced in VS Code's debug API.

 export function openScript(session: vscode.DebugSession | undefined, source: Source) {
	let uri: vscode.Uri;
	if (source.sourceReference) {
		let debug = `debug:${encodeURIComponent(source.path)}`;
		let sep = '?';
		if (session) {
			debug += `${sep}session=${encodeURIComponent(session.id)}`;
			sep = '&';
		}
		debug += `${sep}ref=${source.sourceReference}`;
		uri = vscode.Uri.parse(debug);
	} else {
		uri = vscode.Uri.file(source.path);
	}
	vscode.workspace.openTextDocument(uri).then(doc => vscode.window.showTextDocument(doc));
}

New API proposal:

export function openScript(session: vscode.DebugSession | undefined, source: Source) {
	const uri = session.createDebugUri(src);
	vscode.workspace.openTextDocument(uri).then(doc => vscode.window.showTextDocument(doc));
}

Alternative:

export function openScript(session: vscode.DebugSession | undefined, source: Source) {
	session.showSource(source);
}

Open issue:

"Source" is a DAP construct which is not available in VS Code's debug API.

[weinand]

After implementing the proposal from above it became clear, that the API does not require an active debug session. As a consequence I've moved the asDebugSourceUri method from the DebugSession class to the debug namespace.

2nd proposal:

/**
 * A DebugSource is an opaque stand-in type for the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) 
   type defined in the Debug Adapter Protocol.
 */
export interface DebugSource {
  // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source).
}

export namespace debug {

	/**
	 * Converts a "Source" descriptor object received via the Debug Adapter Protocol into a Uri that can be used to load its contents.
	 * If the source descriptor is based on a path, a file Uri is returned.
	 * If the source descriptor uses a reference number, a specific debug Uri (scheme 'debug') is constructed that requires a corresponding VS Code ContentProvider and a running debug session
	 *
	 * If the "Source" descriptor has insufficient information for creating the Uri, an error is thrown.
	 *
	 * @param source An object conforming to the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol.
	 * @param session An optional debug session that will be used when the source descriptor uses a reference number to load the contents from an active debug session.
	 * @return A uri that can be used to load the contents of the source.
	 */
	export function asDebugSourceUri(source: DebugSource, session?: DebugSession): Uri;
}