feat: add instruction reference to GotoTargets request

Author: DrSergei

changelog.md

@@ -10,6 +10,7 @@ sectionid: changelog
   * Clarify how `StackTraceArguments.format` applies
   * Clarify the default behavior of `ContinuedEvent.allThreadsContinued`
   * Clarify representation of breakpoints after a `changed` event
+  * Add optional `instructionReference` and `offset` properties to the `gotoTargets` request
 
 * 1.69.x
   * Clarify the flow diagram to start a debug session

debugAdapterProtocol.json

@@ -2767,6 +2767,14 @@
 				"column": {
 					"type": "integer",
 					"description": "The position within `line` for which the goto targets are determined. It is measured in UTF-16 code units and the client capability `columnsStartAt1` determines whether it is 0- or 1-based."
+				},
+				"instructionReference": {
+					"type": "string",
+					"description": "The instruction reference for which the goto targets are determined.\nThis should be a memory or instruction pointer reference from an `EvaluateResponse`, `Variable`, `StackFrame`, `GotoTarget`, or `Breakpoint`. Clients may set this property only if the `supportsGotoInstructionTargets ` is true. If `instructionReference` is set, the debug adapter should ignore the `line`, `column`, and `source` on the request and clients may set them to zero or empty values."
+				},
+				"offset": {
+					"type": "integer",
+					"description": "The offset from the instruction reference in bytes.\nThis can be negative. This may only be provided when an `instructionReference` is included in the request."
 				}
 			},
 			"required": [ "source", "line" ]
@@ -3352,6 +3360,10 @@
 				"supportsANSIStyling": {
 					"type": "boolean",
 					"description": "The debug adapter supports ANSI escape sequences in styling of `OutputEvent.output` and `Variable.value` fields."
+				},
+				"supportsGotoInstructionTargets": {
+					"type": "boolean",
+					"description": "The debug adapter supports the `instructionReference` and `offset` fields in the `gotoTargets` request."
 				}
 			}
 		},

specification.md

@@ -491,7 +491,7 @@ interface OutputEvent extends Event {
 
 ### <a name="Events_Breakpoint" class="anchor"></a>:arrow_left: Breakpoint Event
 
-The event indicates that some information about a breakpoint has changed.
+The event indicates that some information about a breakpoint has changed. While debug adapters may notify the clients of `changed` breakpoints using this event, clients should continue to use the breakpoint's original properties when updating a source's breakpoints in the `breakpoint` request.
 
 ```typescript
 interface BreakpointEvent extends Event {
@@ -3023,6 +3023,24 @@ interface GotoTargetsArguments {
    * determines whether it is 0- or 1-based.
    */
   column?: number;
+
+  /**
+   * The instruction reference for which the goto targets are determined.
+   * This should be a memory or instruction pointer reference from an
+   * `EvaluateResponse`, `Variable`, `StackFrame`, `GotoTarget`, or
+   * `Breakpoint`. Clients may set this property only if the
+   * `supportsGotoInstructionTargets ` is true. If `instructionReference` is
+   * set, the debug adapter should ignore the `line`, `column`, and `source` on
+   * the request and clients may set them to zero or empty values.
+   */
+  instructionReference?: string;
+
+  /**
+   * The offset from the instruction reference in bytes.
+   * This can be negative. This may only be provided when an
+   * `instructionReference` is included in the request.
+   */
+  offset?: number;
 }
 ```
 
@@ -3501,8 +3519,11 @@ interface Capabilities {
   supportsCompletionsRequest?: boolean;
 
   /**
-   * The set of characters that should trigger completion in a REPL. If not
-   * specified, the UI should assume the `.` character.
+   * The set of characters that should automatically trigger a completion
+   * request in a REPL. If not specified, the client should assume the `.`
+   * character. The client may trigger additional completion requests on
+   * characters such as ones that make up common identifiers, or as otherwise
+   * requested by a user.
    */
   completionTriggerCharacters?: string[];
 
@@ -3672,6 +3693,12 @@ interface Capabilities {
    * `OutputEvent.output` and `Variable.value` fields.
    */
   supportsANSIStyling?: boolean;
+
+  /**
+   * The debug adapter supports the `instructionReference` and `offset` fields
+   * in the `gotoTargets` request.
+   */
+  supportsGotoInstructionTargets?: boolean;
 }
 ```