feat: add locations request and references to variable types (#494)

* feat: add locations request and references to variable types

* comments

* integer type

_data/specification-toc.yml

@@ -85,6 +85,8 @@
       anchor: Requests_Launch
     - title: LoadedSources
       anchor: Requests_LoadedSources
+    - title: Locations
+      anchor: Requests_Locations
     - title: Modules
       anchor: Requests_Modules
     - title: Next

changelog.md

@@ -6,6 +6,12 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.68.x
+  * Add `locationReference`s to Variable-related data types to allow navigation to declarations, and a corresponding `locations` request.
+  * Clarify the meaning of "system process"
+  * Clarify the lifetime of `variableReference`s after a `setVariable` call
+  * Fix typographic errors in `StackFrame.canRestart`
+
 * 1.67.x
   * Add `line`, `column`, and `source` location attributions to `EvaluateArguments`
   * Add `returnValue` as a well-known `Scope.presentationHint`

debugAdapterProtocol.json

@@ -392,6 +392,10 @@
 							"data": {
 								"type": [ "array", "boolean", "integer", "null", "number" , "object", "string" ],
 								"description": "Additional data to report. For the `telemetry` category the data is sent to telemetry, for the other categories the data is shown in JSON format."
+							},
+							"locationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the new value is declared. For example, if the logged value is function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": ["output"]
@@ -2244,6 +2248,10 @@
 							"memoryReference": {
 								"type": "string",
 								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
+							},
+							"valueLocationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the new value is declared. For example, if the new value is function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": [ "value" ]
@@ -2574,6 +2582,10 @@
 							"memoryReference": {
 								"type": "string",
 								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
+							},
+							"valueLocationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the returned value is declared. For example, if a function pointer is returned, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": [ "result", "variablesReference" ]
@@ -2657,6 +2669,10 @@
 							"memoryReference": {
 								"type": "string",
 								"description": "A memory reference to a location appropriate for this result.\nFor pointer type eval results, this is generally a reference to the memory address contained in the pointer.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
+							},
+							"valueLocationReference": {
+								"type": "integer",
+								"description": "A reference that allows the client to request the location where the new value is declared. For example, if the new value is function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 							}
 						},
 						"required": [ "value" ]
@@ -3083,6 +3099,68 @@
 			}]
 		},
 
+		"LocationsRequest": {
+			"allOf": [ { "$ref": "#/definitions/Request" }, {
+				"type": "object",
+				"description": "Looks up information about a location reference previously returned by the debug adapter.",
+				"properties": {
+					"command": {
+						"type": "string",
+						"enum": [ "locations" ]
+					},
+					"arguments": {
+						"$ref": "#/definitions/LocationsArguments"
+					}
+				},
+				"required": [ "command", "arguments" ]
+			}]
+		},
+		"LocationsArguments": {
+			"type": "object",
+			"description": "Arguments for `locations` request.",
+			"properties": {
+				"locationReference": {
+					"type": "integer",
+					"description": "Location reference to resolve."
+				}
+			},
+			"required": [ "locationReference" ]
+		},
+		"LocationsResponse": {
+			"allOf": [ { "$ref": "#/definitions/Response" }, {
+				"type": "object",
+				"description": "Response to `locations` request.",
+				"properties": {
+					"body": {
+						"type": "object",
+						"properties": {
+							"source": {
+								"$ref": "#/definitions/Source",
+								"description": "The source containing the location; either `source.path` or `source.sourceReference` must be specified."
+							},
+							"line": {
+								"type": "integer",
+								"description": "The line number of the location. The client capability `linesStartAt1` determines whether it is 0- or 1-based."
+							},
+							"column": {
+								"type": "integer",
+								"description": "Position of the location within the `line`. It is measured in UTF-16 code units and the client capability `columnsStartAt1` determines whether it is 0- or 1-based. If no column is given, the first position in the start line is assumed."
+							},
+							"endLine": {
+								"type": "integer",
+								"description": "End line of the location, present if the location refers to a range.  The client capability `linesStartAt1` determines whether it is 0- or 1-based."
+							},
+							"endColumn": {
+								"type": "integer",
+								"description": "End position of the location within `endLine`, present if the location refers to a range. It is measured in UTF-16 code units and the client capability `columnsStartAt1` determines whether it is 0- or 1-based."
+							}
+						},
+						"required": [ "source", "line" ]
+					}
+				}
+			}]
+		},
+
 		"Capabilities": {
 			"type": "object",
 			"title": "Types",
@@ -3632,6 +3710,14 @@
 				"memoryReference": {
 					"type": "string",
 					"description": "A memory reference associated with this variable.\nFor pointer type variables, this is generally a reference to the memory address contained in the pointer.\nFor executable data, this reference may later be used in a `disassemble` request.\nThis attribute may be returned by a debug adapter if corresponding capability `supportsMemoryReferences` is true."
+				},
+				"declarationLocationReference": {
+					"type": "integer",
+					"description": "A reference that allows the client to request the location where the variable is declared. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
+				},
+				"valueLocationReference": {
+					"type": "integer",
+					"description": "A reference that allows the client to request the location where the variable's value is declared. For example, if the variable contains a function pointer, the adapter may be able to look up the function's location. This should be present only if the adapter is likely to be able to resolve the location.\n\nThis reference shares the same lifetime as the `variablesReference`. See 'Lifetime of Object References' in the Overview section for details."
 				}
 			},
 			"required": [ "name", "value", "variablesReference" ]

specification.md

@@ -464,6 +464,18 @@ interface OutputEvent extends Event {
      * to telemetry, for the other categories the data is shown in JSON format.
      */
     data?: any;
+
+    /**
+     * A reference that allows the client to request the location where the new
+     * value is declared. For example, if the logged value is function pointer,
+     * the adapter may be able to look up the function's location. This should
+     * be present only if the adapter is likely to be able to resolve the
+     * location.
+     * 
+     * This reference shares the same lifetime as the `variablesReference`. See
+     * 'Lifetime of Object References' in the Overview section for details.
+     */
+    locationReference?: string;
   };
 }
 ```
@@ -2437,6 +2449,17 @@ interface SetVariableResponse extends Response {
      * capability `supportsMemoryReferences` is true.
      */
     memoryReference?: string;
+
+    /**
+     * A reference that allows the client to request the location where the new
+     * value is declared. For example, if the new value is function pointer, the
+     * adapter may be able to look up the function's location. This should be
+     * present only if the adapter is likely to be able to resolve the location.
+     * 
+     * This reference shares the same lifetime as the `variablesReference`. See
+     * 'Lifetime of Object References' in the Overview section for details.
+     */
+    valueLocationReference?: string;
   };
 }
 ```
@@ -2770,6 +2793,18 @@ interface EvaluateResponse extends Response {
      * capability `supportsMemoryReferences` is true.
      */
     memoryReference?: string;
+
+    /**
+     * A reference that allows the client to request the location where the
+     * returned value is declared. For example, if a function pointer is
+     * returned, the adapter may be able to look up the function's location.
+     * This should be present only if the adapter is likely to be able to
+     * resolve the location.
+     * 
+     * This reference shares the same lifetime as the `variablesReference`. See
+     * 'Lifetime of Object References' in the Overview section for details.
+     */
+    locationReference?: string;
   };
 }
 ```
@@ -2876,6 +2911,17 @@ interface SetExpressionResponse extends Response {
      * capability `supportsMemoryReferences` is true.
      */
     memoryReference?: string;
+
+    /**
+     * A reference that allows the client to request the location where the new
+     * value is declared. For example, if the new value is function pointer, the
+     * adapter may be able to look up the function's location. This should be
+     * present only if the adapter is likely to be able to resolve the location.
+     * 
+     * This reference shares the same lifetime as the `variablesReference`. See
+     * 'Lifetime of Object References' in the Overview section for details.
+     */
+    valueLocationReference?: string;
   };
 }
 ```
@@ -3298,6 +3344,74 @@ interface DisassembleResponse extends Response {
 }
 ```
 
+### <a name="Requests_Locations" class="anchor"></a>:leftwards_arrow_with_hook: Locations Request
+
+Looks up information about a location reference previously returned by the debug adapter.
+
+```typescript
+interface LocationsRequest extends Request {
+  command: 'locations';
+
+  arguments: LocationsArguments;
+}
+```
+
+Arguments for `locations` request.
+
+<a name="Types_LocationsArguments" class="anchor"></a>
+```typescript
+interface LocationsArguments {
+  /**
+   * Location reference to resolve.
+   */
+  locationReference: string;
+}
+```
+
+Response to `locations` request.
+
+<a name="Types_LocationsResponse" class="anchor"></a>
+```typescript
+interface LocationsResponse extends Response {
+  body?: {
+    /**
+     * The source containing the location; either `source.path` or
+     * `source.sourceReference` must be specified.
+     */
+    source: Source;
+
+    /**
+     * The line number of the location. The client capability `linesStartAt1`
+     * determines whether it is 0- or 1-based.
+     */
+    line: number;
+
+    /**
+     * Position of the location within the `line`. It is measured in UTF-16 code
+     * units and the client capability `columnsStartAt1` determines whether it
+     * is 0- or 1-based. If no column is given, the first position in the start
+     * line is assumed.
+     */
+    column?: number;
+
+    /**
+     * End line of the location. If no end line is given, then the end line is
+     * assumed to be the start line. The client capability `linesStartAt1`
+     * determines whether it is 0- or 1-based.
+     */
+    endLine?: number;
+
+    /**
+     * End position of the location within `endLine`. It is measured in UTF-16
+     * code units and the client capability `columnsStartAt1` determines whether
+     * it is 0- or 1-based. If no end column is given, the last position in the
+     * end line is assumed.
+     */
+    endColumn?: number;
+  };
+}
+```
+
 ## <a name="Types" class="anchor"></a>Types
 
 ### <a name="Types_Capabilities" class="anchor"></a>Capabilities
@@ -4076,6 +4190,28 @@ interface Variable {
    * capability `supportsMemoryReferences` is true.
    */
   memoryReference?: string;
+
+  /**
+   * A reference that allows the client to request the location where the
+   * variable is declared. This should be present only if the adapter is likely
+   * to be able to resolve the location.
+   * 
+   * This reference shares the same lifetime as the `variablesReference`. See
+   * 'Lifetime of Object References' in the Overview section for details.
+   */
+  declarationLocationReference?: string;
+
+  /**
+   * A reference that allows the client to request the location where the
+   * variable's value is declared. For example, if the variable contains a
+   * function pointer, the adapter may be able to look up the function's
+   * location. This should be present only if the adapter is likely to be able
+   * to resolve the location.
+   * 
+   * This reference shares the same lifetime as the `variablesReference`. See
+   * 'Lifetime of Object References' in the Overview section for details.
+   */
+  valueLocationReference?: string;
 }
 ```