Propose an API that enables extensions to drive multi document highlights

[jrieken]

Testing #196342

We have an internal API to support X-document highlights. Our current implementation is very clever but we should propose an API/LSP spec so that extensions can drive this feature all the way

[Yoyokrazy]

This is being worked on in conjunction with #196240. This API is being proposed to drive the development of semantic multi-document highlights, rather than the current textual functionality. The shape is as proposed as follows:

/**
 * Represents a collection of document highlights from multiple documents.
 */
export class MultiDocumentHighlight {

	/**
	 * The URI of the document containing the highlights.
	 */
	uri: Uri;

	/**
	 * The highlights for the document.
	 */
	highlights: DocumentHighlight[];

	/**
	 * Creates a new instance of MultiDocumentHighlight.
	 * @param uri The URI of the document containing the highlights.
	 * @param highlights The highlights for the document.
	 */
	constructor(uri: Uri, highlights: DocumentHighlight[]);
}

export interface MultiDocumentHighlightProvider {

	/**
	 * Provide a set of document highlights, like all occurrences of a variable or
	 * all exit-points of a function.
	 *
	 * @param document The document in which the command was invoked.
	 * @param position The position at which the command was invoked.
	 * @param otherDocuments An array of additional valid documents for which highlights should be provided.
	 * @param token A cancellation token.
	 * @returns A Map containing a mapping of the Uri of a document to the document highlights or a thenable that resolves to such. The lack of a result can be
	 * signaled by returning `undefined`, `null`, or an empty map.
	 */
	provideMultiDocumentHighlights(document: TextDocument, position: Position, otherDocuments: TextDocument[], token: CancellationToken): ProviderResult<MultiDocumentHighlight[]>;
}

namespace languages {

	/**
	 * Register a multi document highlight provider.
	 *
	 * Multiple providers can be registered for a language. In that case providers are sorted
	 * by their {@link languages.match score} and groups sequentially asked for document highlights.
	 * The process stops when a provider returns a `non-falsy` or `non-failure` result.
	 *
	 * @param selector A selector that defines the documents this provider is applicable to.
	 * @param provider A multi-document highlight provider.
	 * @returns A {@link Disposable} that unregisters this provider when being disposed.
	 */
	export function registerMultiDocumentHighlightProvider(selector: DocumentSelector, provider: MultiDocumentHighlightProvider): Disposable;
}

[jrieken]

@Yoyokrazy let's keep this issue open and use it for the finalization of the API