Proposal: Allow a language server to provide a reference content for a specific uri scheme

[david-driscoll]

A cool feature that atom and vscode has is the ability to take a scheme and the editor would load the text for that scheme from the server instead of from say disk.

This is used in OmniSharp to load metadata of a decompiled types.

A full proposal as per the contributing guidelines to come soon.

New methods

• workspace/getReferenceDocument - Get text content from the workspace
• workspace/openDocument - Allow the server to have the client open a document, eg. in response to goto definition on something that doesn't exist.

interface WorkspaceClientCapabilities {
	/**
	 * Capabilities specific to the `workspace/getReferenceDocument` request.
	 */
	referenceDocument?: {
		/**
		 * Execute command supports dynamic registration.
		 */
		dynamicRegistration?: boolean;
	};
	/**
	 * Capabilities specific to the `workspace/openDocument` request.
	 */
	openDocument?: {
		/**
		 * Execute command supports dynamic registration.
		 */
		dynamicRegistration?: boolean;
	};
}

interface ServerCapabilities {
	/**
	 * Capabilities specific to the `workspace/getReferenceDocument` request.
	 */
	referenceDocumentProvider?: {
		/**
		 * Reference schemes supported by this server
		 */
		schemes?: string[];
	};
}

// registration options for `workspace/getReferenceDocument`
interface ReferenceDocumentRegistrationOptions {
	schemes?: string[];
}

// workspace/getReferenceDocument
// request
interface GetSchemeContentParams {
	/**
	 * The text document's URI.
	 */
        uri: DocumentUri;
}
// returns
interface ReferenceDocumentItem {
	/**
	 * The text document's URI.
	 */
	uri: DocumentUri;

	/**
	 * The text document's language identifier.
	 */
	languageId: string;

	/**
	 * The content of the opened text document.
	 */
	text: string;
}

// notification
interface OpenDocumentParams {
	/**
	 * The text document's URI.
	 */
	uri: DocumentUri;
}

[bmewburn]

Looks like remote development scenarios are getting some attention in vscode microsoft/vscode#29194 . In light of this, what is the status of this proposal?

The theme appears to be to maintain a flexible approach to how a server can obtain workspace documents for indexing and such. Will LSP continue in this flexible direction? Or will there be a move towards clients being the authority on all workspace content? I like the idea of the client being the source of all documents, with the server being workspace ignorant and this proposal would help that. Though for a language server to be usable across different clients, some of which may not have a means to provide unopened workspace content, a server needs to then have it's own way of accessing workspace documents.

So where is all this heading? Will we see clients and servers both having to implement there own local file system providers, ftp providers etc?

[dbaeumer]

I am the opinion that a server should allow to provide the content for specific schemes. Since the LSP since a while allows to proposal addition request and notifications this is IMO a good candidate to do so. Guidelines on how this should be done are here: https://github.com/Microsoft/language-server-protocol/blob/master/contributing.md

[DavidGoldman]

Any update here? It has been awhile since the last update. This seems useful for SourceKit-LSP to allow it to provide virtual documents for a Swift module interface or Objective-C interface counterpart of a Swift file

[dbaeumer]

A PR implementing it would be highly appreciated. Guidelines how to do it are here: https://github.com/microsoft/language-server-protocol/blob/master/contributing.md

[SamB]

It has occurred to me that making this work in general would probably require the LSP client to assign prefixes, since there could be many instances of (more-or-less) the same LSP in play at once.

[fwcd]

Is this really a dupe of #689? At least for the use case of macro expansions it would be convenient also to be able to peek a document at a specific location (perhaps with a workspace/peekDocument request? Or by adding an optional peek position to the proposed workspace/openDocument?)

See swiftlang/vscode-swift#621 for a specific use case.

[mickaelistria]

perhaps with a workspace/peekDocument request

This is the approach taken (in a custom LS extension) by JDT-LS and it works fine. We would really welcome a standard operation to achieve that workspace/documentContent.
Declaration of the specific schemes handled by the Language Server doesn't seem very necessary in a 1st iteration. I wouldn't make it a blocker for the addition of workspace/documentContent.

[dbaeumer]

Implemented and documented for the 3.18 release