Add support for completionList.applyKind to determine how values from completionList.itemDefaults and completion are combined. (#2018)

* Add support for `completionList.applyKind` to determine how values from `completionList.itemDefaults` and `completion` are combined.

Fixes https://github.com/microsoft/language-server-protocol/issues/1802

* Update completion.md

* Simplify by removing distinction between null/undefined

* Use a single client capability + add ApplyKind enum/type

* Make this clearer

* Minor fixes

- commitCharacters isn't allowed to be null so no point mentioning this
- Fix missing quote
- Fix error in ApplyKind type (either needs "typeof" or to use literals, and other things use literals)

* Change ApplyKind to be integers

* Typos

---------

Co-authored-by: Dirk Bäumer <dirkb@microsoft.com>

_specifications/lsp/3.18/language/completion.md

@@ -166,6 +166,21 @@ export interface CompletionClientCapabilities {
 		 * @since 3.17.0
 		 */
 		itemDefaults?: string[];
+
+		/**
+		 * Specifies whether the client supports `CompletionList.applyKind` to
+		 * indicate how supported values from `completionList.itemDefaults`
+		 * and `completion` will be combined.
+		 * 
+		 * If a client supports `applyKind` it must support it for all fields
+		 * that it supports that are listed in `CompletionList.applyKind`. This
+		 * means when clients add support for new/future fields in completion
+		 * items the MUST also support merge for them if those fields are
+		 * defined in `CompletionList.applyKind`.
+		 *
+		 * @since 3.18.0
+		 */
+		applyKindSupport?: boolean;
 	}
 }
 ```
@@ -338,7 +353,9 @@ export interface CompletionList {
 	 * be used if a completion item itself doesn't specify the value.
 	 *
 	 * If a completion list specifies a default value and a completion item
-	 * also specifies a corresponding value, the one from the item is used.
+	 * also specifies a corresponding value, the rules for combining these are
+	 * defined by `applyKinds` (if the client supports it), defaulting to
+	 * ApplyKind.Replace.
 	 *
 	 * Servers are only allowed to return default values if the client
 	 * signals support for this via the `completionList.itemDefaults`
@@ -386,6 +403,73 @@ export interface CompletionList {
 		data?: LSPAny;
 	}
 
+	/**
+	 * Specifies how fields from a completion item should be combined with those
+	 * from `completionList.itemDefaults`.
+	 * 
+	 * If unspecified, all fields will be treated as ApplyKind.Replace.
+	 * 
+	 * If a field's value is ApplyKind.Replace, the value from a completion item
+	 * (if provided and not `null`) will always be used instead of the value
+	 * from `completionItem.itemDefaults`.
+	 * 
+	 * If a field's value is ApplyKind.Merge, the values will be merged using
+	 * the rules defined against each field below.
+	 *
+	 * Servers are only allowed to return `applyKind` if the client
+	 * signals support for this via the `completionList.applyKindSupport`
+	 * capability.
+	 *
+	 * @since 3.18.0
+	 */
+	applyKind?: {
+		/**
+		 * Specifies whether commitCharacters on a completion will replace or be
+		 * merged with those in `completionList.itemDefaults.commitCharacters`.
+		 * 
+		 * If ApplyKind.Replace, the commit characters from the completion item
+		 * will always be used unless not provided, in which case those from
+		 * `completionList.itemDefaults.commitCharacters` will be used. An
+		 * empty list can be used if a completion item does not have any commit
+		 * characters and also should not use those from
+		 * `completionList.itemDefaults.commitCharacters`.
+		 * 
+		 * If ApplyKind.Merge the commitCharacters for the completion will be
+		 * the union of all values in both
+		 * `completionList.itemDefaults.commitCharacters` and the completion's
+		 * own `commitCharacters`.
+		 *
+		 * @since 3.18.0
+		 */
+		commitCharacters?: ApplyKind;
+
+		/**
+		 * Specifies whether the `data` field on a completion will replace or
+		 * be merged with data from `completionList.itemDefaults.data`.
+		 * 
+		 * If ApplyKind.Replace, the data from the completion item will be used
+		 * if provided (and not `null`), otherwise
+		 * `completionList.itemDefaults.data` will be used. An empty object can
+		 * be used if a completion item does not have any data but also should
+		 * not use the value from `completionList.itemDefaults.data`.
+		 * 
+		 * If ApplyKind.Merge, a shallow merge will be performed between
+		 * `completionList.itemDefaults.data` and the completion's own data
+		 * using the following rules:
+		 * 
+		 * - If a completion's `data` field is not provided (or `null`), the
+		 *   entire `data` field from `completionList.itemDefaults.data` will be
+		 *   used as-is.
+		 * - If a completion's `data` field is provided, each field will
+		 *   overwrite the field of the same name in
+		 *   `completionList.itemDefaults.data` but no merging of nested fields
+		 *   within that value will occur.
+		 *
+		 * @since 3.18.0
+		 */
+		data?: ApplyKind;
+	}
+
 	/**
 	 * The completion items.
 	 */
@@ -525,6 +609,40 @@ export interface CompletionItemLabelDetails {
 }
 ```
 
+<div class="anchorHolder"><a href="#applyKind" name="applyKind" class="linkableAnchor"></a></div>
+
+```typescript
+/**
+ * Defines how values from a set of defaults and an individual item will be
+ * merged.
+ *
+ * @since 3.18.0
+ */
+export namespace ApplyKind {
+	/**
+	 * The value from the individual item (if provided and not `null`) will be
+	 * used instead of the default.
+	 */
+	export const Replace: 1 = 1;
+
+	/**
+	 * The value from the item will be merged with the default.
+	 *
+	 * The specific rules for mergeing values are defined against each field
+	 * that supports merging.
+	 */
+	export const Merge: 2 = 2;
+}
+
+/**
+ * Defines how values from a set of defaults and an individual item will be
+ * merged.
+ *
+ * @since 3.18.0
+ */
+export type ApplyKind = 1 | 2;
+```
+
 <div class="anchorHolder"><a href="#completionItem" name="completionItem" class="linkableAnchor"></a></div>
 
 ```typescript

_specifications/lsp/3.18/specification.md

@@ -737,6 +737,7 @@ Since 3.17 there is a meta model describing the LSP protocol:
 * Support for snippets in text document edits.
 * Support for debug message kind.
 * Client capability to enumerate properties that can be resolved for code lenses.
+* Added support for `completionList.applyKind` to determine how values from `completionList.itemDefaults` and `completion` are combined.
 
 
 #### <a href="#version_3_17_0" name="version_3_17_0" class="anchor">3.17.0 (05/10/2022)</a>