Add read/write access tags to call hierarchy and find references (fix #951)

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/Protocol.xtend

@@ -40,6 +40,7 @@ import org.eclipse.lsp4j.jsonrpc.validation.NonNull
 import org.eclipse.lsp4j.jsonrpc.ProtocolDeprecated
 import org.eclipse.lsp4j.jsonrpc.ProtocolDraft
 import org.eclipse.lsp4j.jsonrpc.ProtocolSince
+import java.util.Collections
 
 @JsonRpcData
 class DynamicRegistrationCapabilities {
@@ -848,6 +849,17 @@ class SignatureHelpCapabilities extends DynamicRegistrationCapabilities {
  */
 @JsonRpcData
 class ReferencesCapabilities extends DynamicRegistrationCapabilities {
+
+    /**
+     * <p>Determines whether the client supports and prefers {@link Reference} items instead
+     * of {@link Location} items. If this value is missing, the server assumes that the
+     * client accepts Location items as defined in earlier versions of the protocol.</p>
+     * 
+     * <p>This is an LSP <b>proposal</b>. See <a href="https://github.com/microsoft/language-server-protocol/pull/2226">PR</a></p>
+     */
+    @ProtocolDraft
+    Boolean referenceItemsSupport;
+
 	new() {
 	}
 
@@ -1695,6 +1707,16 @@ class TypeHierarchyRegistrationOptions extends AbstractTextDocumentRegistrationA
 @ProtocolSince("3.16.0")
 @JsonRpcData
 class CallHierarchyCapabilities extends DynamicRegistrationCapabilities {
+
+    /**
+     * <p>Determines whether the client supports reference tags. If the value is missing,
+     * the server assumes that the client does not support reference tags.</p>
+     * 
+     * <p>This is an LSP <b>proposal</b>. See <a href="https://github.com/microsoft/language-server-protocol/pull/2226">PR</a></p>
+     */
+    @ProtocolDraft
+    Boolean referenceTagsSupport;
+
 	new() {
 	}
 
@@ -5287,6 +5309,42 @@ class Location {
 	}
 }
 
+/**
+ * <p>Represents a reference to a symbol and describes the kind of reference, e.g. read or write access,
+ * in addition to its location in a resource.</p>
+ * 
+ * <p>This is an LSP <b>proposal</b>. See <a href="https://github.com/microsoft/language-server-protocol/pull/2226">PR</a></p>
+ */
+@ProtocolDraft
+@JsonRpcData
+class Reference {
+    @NonNull
+    Location location
+
+    @NonNull
+    List<ReferenceTag> referenceTags
+
+    new() {
+    }
+
+    new(@NonNull Location location) {
+        this(location, Collections.emptyList())
+    }
+
+    new(@NonNull String uri, @NonNull Range range) {
+        this(new Location(uri, range), Collections.emptyList())
+    }
+
+    new(@NonNull String uri, @NonNull Range range, @NonNull List<ReferenceTag> referenceTags) {
+        this(new Location(uri, range), referenceTags)
+    }
+
+    new(@NonNull Location location, @NonNull List<ReferenceTag> referenceTags) {
+        this.location = Preconditions.checkNotNull(location, 'location')
+        this.referenceTags = Preconditions.checkNotNull(referenceTags, 'referenceTags')
+    }
+}
+
 /**
  * Represents a link between a source and a target location.
  */
@@ -8950,6 +9008,14 @@ class CallHierarchyItem {
 	 * Tags for this item.
 	 */
 	List<SymbolTag> tags
+
+	/**
+	 * <p>Reference tags for this item.</p>
+	 * 
+	 * <p>This is an LSP <b>proposal</b>. See <a href="https://github.com/microsoft/language-server-protocol/pull/2226">PR</a></p>
+	 */
+	@ProtocolDraft
+	List<ReferenceTag> referenceTags
 
 	/**
 	 * The resource identifier of this item.

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/ReferenceTag.java

@@ -0,0 +1,53 @@
+/******************************************************************************
+ * Copyright (c) 2026 Advantest Europe GmbH and others.
+ * 
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ * 
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ ******************************************************************************/
+
+package org.eclipse.lsp4j;
+
+import org.eclipse.lsp4j.jsonrpc.ProtocolDraft;
+
+
+/**
+ * <p>Reference tags represent additional details in CallHierarchyItems and References to adapt their rendering.</p>
+ * 
+ * <p>This is an LSP <b>proposal</b>. See <a href="https://github.com/microsoft/language-server-protocol/pull/2226">PR</a></p>
+ */
+@ProtocolDraft
+public enum ReferenceTag {
+
+	/**
+	 * Render a CallHierarchyItem or Reference as read access, e.g. in a call hierarchy.
+	 */
+	Read(1),
+
+	/**
+	 * Render a CallHierarchyItem or Reference as write access, e.g. in a call hierarchy.
+	 */
+	Write(2);
+
+
+	private final int value;
+
+	ReferenceTag(int value) {
+		this.value = value;
+	}
+
+	public int getValue() {
+		return value;
+	}
+
+	public static ReferenceTag forValue(int value) {
+		ReferenceTag[] allValues = ReferenceTag.values();
+		if (value < 1 || value > allValues.length)
+			throw new IllegalArgumentException("Illegal enum value: " + value);
+		return allValues[value - 1];
+	}
+}

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/services/TextDocumentService.java

@@ -73,6 +73,7 @@
 import org.eclipse.lsp4j.PrepareRenameParams;
 import org.eclipse.lsp4j.PrepareRenameResult;
 import org.eclipse.lsp4j.Range;
+import org.eclipse.lsp4j.Reference;
 import org.eclipse.lsp4j.ReferenceParams;
 import org.eclipse.lsp4j.RenameParams;
 import org.eclipse.lsp4j.SelectionRange;
@@ -220,6 +221,22 @@ default CompletableFuture<Either<List<? extends Location>, List<? extends Locati
 	default CompletableFuture<List<? extends Location>> references(ReferenceParams params) {
 		throw new UnsupportedOperationException();
 	}
+
+	/**
+	 * <p>The references request is sent from the client to the server to resolve
+	 * project-wide references for the symbol denoted by the given text document
+	 * position.</p>
+	 * 
+	 * Registration Options: {@link org.eclipse.lsp4j.ReferenceRegistrationOptions}
+	 * 
+	 * <p>This is an LSP <b>proposal</b>. See <a href="https://github.com/microsoft/language-server-protocol/pull/2226">PR</a>
+	 * This method is planned to replace {@link #references(ReferenceParams)} and could be renamed to 'references' in future.</p>
+	 */
+	// TODO introduce this new method (avoid a breaking change) or replace #references(ReferenceParams)?
+	@JsonRequest
+	default CompletableFuture<Either<List<Location>,List<Reference>>> referencesWithTags(ReferenceParams params) {
+		throw new UnsupportedOperationException();
+	}
 
 	/**
 	 * The document highlight request is sent from the client to the server to