Add Inline value provider api for debugging

[mjbvz]

From microsoft/vscode#119489

Background

The new inline value api for VS Code lets language extensions tell the debugger which values should be shown directly in a file while debugging. Without this API, VS Code uses a generic method for determining which values to show. This ends up showing many irrelevant values to the user

See microsoft/vscode#119489 for an example of this

Feature Request

We'd like to use the TypeScript server's language smarts to implement the VS Code inline value api so that only relevant values are shown.

Here's a potential shape of the API based on the vscode inline value API

// For debugging, we request inline values at a specific location in a file
interface InlineValueRequestArgs extends FileLocationRequestArgs {}

interface InlineValueResponse  extends Response {
   body: InlineValue[];
}

// Support two types of inline values: simple ones that can be looked up by name, and more complex ones
// that require evaluating an expression
type InlineValue = InlineValueVariableLookup | InlineValueEvaluatableExpression;

// A value that can be looked up by name.
// This is mostly just an optimization for a common case of inline values 
interface InlineValueVariableLookup {
    // Span in code of the identifier
    readonly span: TextSpan;

    // Optional variable name to look up. If not specified, uses the name from `span`
    // TODO: Is this needed for TS?
    readonly variableName?: string;
}

// A value which is shown by evaluating a given expression
interface InlineValueEvaluatableExpression {
    // Span in code of the expression
    readonly span: TextSpan;

    // Optional expression to evaluate. If not specified, uses the expression from `span`
    // TODO: Is this needed for TS?
    readonly expression?: string;
}

Behavior

Some notes on how the inline value provider should work (copied from @connor4312):

• The debugger should handle source maps, so the provider should only have to worry about the requested file

• Inline values should only be provided in the current and parent scopes

• Declarations and assignments assignments should evaluate the declared or assigned expression, bar in bar = foo() or foo in function foo() {}

• Conditional expressions (ternary or if statements) should evaluate the conditional and none of its children, !foo && bar in if (!foo && bar)

• Property assignments should be evaluated, foo() in { x: foo() }

Here's a small example of some inline values:

function double(n: number) { // eval('double') -> double()
  return n * 2;
}

let x = 1; // InlineValueVariableLookup for x here

if (x === 2) { // eval(x === 2) -> false
  x *= 2; // this line should NOT be evaluated since it's not the scope or its parents
}

if (x === 1) { // eval(x === 1) -> true
  x *= 2; // InlineValueVariableLookup for x here
  const y = {
    z: x ** 2, // eval(x ** 2) -> 16
  };

  console.log(x); // <-- paused here
}

@connor4312 Is handling this on the VS Code side and should be able to answer any questions regarding this API

/cc @weinand

[mjbvz]

A few notes from our discussion:

Should this command really live in TS core?

Pros:

• We do need some language smarts to handle all cases
• Fits with other apis
• Don't double parse AST
• VS Code doesn't have to worry about AST versioning

Cons:

• TS team doesn't maintain debugger
• Only single client right now (VS Code)

Could TS implement a more generic API instead?

Instead of offering an InlineValueProvider, maybe TS could expose apis for determining scopes and resolving values. VS Code could then use this to implement an inline value provider

Some existing apis that are similar:

• Folding
• Selection ranges

Could we implement this with a TS Server plugin?

Potentially, and this would also potentially make it easier for the VS Code team to maintain

However there is currently no way to add a new command through a plugin. Could we repurpose an existing command instead?

[mjbvz]

@connor4312 The TS team is interested in supporting this feature, but understandably would like to avoid maintaining an API whose expected behavior is tied so closely to the debugger

This leaves a few options:

• Come up with some more generic API building blocks that we could use to implement inline values.

  Are the any other debugger APIs that are similar?

• Implement inline values entirely in VS Code

• Implement in TypeScript but with a component that VS Code maintains

• Implement using a language service plugin

The language service plugin seems like it may be the most interesting, although we'd potentially need to do some work on the TS side to support a new command from a plugin

[sheetalkamat]

Allowing plugins to enable new commands should be doable if we can pass session to the enablePlugin apart from Project. Session already has addProtocolHandler that can be leveraged

[connor4312]

Are the any other debugger APIs that are similar?

The evaluatable expression provider is vaguely similar in that it is a debugger behavior that's driven by language semantics. Though VS Code has a built-in provider that has good enough heuristics for C-style language like J/TS.

I don't have enough knowledge around the architecture of language servers and services to be able to provide an architectural recommendation.

[weinand]

@mjbvz you said:

Instead of offering an InlineValueProvider, maybe TS could expose apis for determining scopes and resolving values. VS Code could then use this to implement an inline value provider

This would be my preferred approach.

Most likely this API could be used for solving a similar set of problems that we have for the debug hover (where our current heuristics is not able to resolve variables to the correct scope). The "evaluatable expression provider" is basically a twin to the "Inline values provider" and could solve the problems by using the same language server APIs.

[weinand]

@mjbvz what is the status of this feature request?
Is the TS team expecting a proposal for your "api for determining scopes and resolving values"?

[mjbvz]

@weinand We are currently late in the TS 4.3 release so I think this would have be scheduled for TS 4.4, which I believe would start development in May and be released in July

@RyanCavanaugh / @DanielRosenwasser It would make more sense for @weinand to talk to someone on the TS team directly instead of going through me. Who would be the best point of contact on the TS team for @weinand to work with on this feature?

[connor4312]

I am also happy to be involved in development here.

[DanielRosenwasser]

I'd say me and @minestarks, but ideally we'd just have the discussion at the weekly editor sync.