Interactive Diagnostics

[mjbvz]

Problem

JS and TS diagnostic messages can get quite large, especially when dealing with frameworks like Vue or react. The TS team has worked to significantly improve and shorten diagnostic messages, including replacing complex type information with ..., however there are still cases where you need to see the full type information. Right now, we have to staticly choose to expand the additional information or not. They would like the user to be able to interactively expand types within a diagnostic

In addition, the overall diagnostic experience could be improved. Two areas identified talking with the TS team:

• Syntax coloring of inline code in diagnostics
• Go to definition in diagnostics

Refs

#11847

Desired User Experience

Consider a diagnostic message T<...>. We would like the ... to be something like a link. Clicking it would expand the diagnostic message to T<Array<...>>, which itself contains another expandable link

Requirements

The main focus is on being able dynamically to expand sections of a diagnostic. We need new VS Code API support for this and then will need languages to adopt this API. However, I think the other two features should be considered while designing the new diagnostics API as they are likely something we would like to support and will influence overall api design

For expansion, we want to be able to:

• Mark arbitrary spans within a diagnostics as expandable
• Lazily compute these expansions, i.e. don't resolve the expansions ahead of time
• Allow expansions to contain other expansions
• Show a progress indicator of some kind while an expansion is being resolved

Many of these features also make sense for quick info hovers

[mjbvz]

DiagnosticPart Api sketch

This api sketch proposes making diagnostic messages a list of parts. Parts would be joined together to form the message rendered in the editor:

interface TextDiagnosticPart {
    readonly type: 'text';

    /**
     * Text rendered in the editor
     */
    readonly text: string;
}

interface ExpansionDiagnosticPart {
    readonly type: 'expansion';

    /**
     * Contents rendered for the expansion, such as the text `...`
     */
    readonly contents: ReaonlyArray<DiagnosticPart>;

    /**
     * Lazily resolves the diagnostics.
     * 
     * The could also be implemented using a provider or commands.
     */
    expand(): Thenable<ReaonlyArray<DiagnosticPart>>;
}

type DiagnosticPart = TextDiagnosticPart | ExpansionDiagnosticPart;

The diagnostic type would then become:

export class Diagnostic {
    ...
	
    message: string | ReadonlyArray<DiagnosticPart>;

     ...
}

Extensions

• The idea of diagnostic parts could be easily extended to clickable links and code:

interface ClickableDiagnosticPart {
    readonly type: 'clickable';

    /**
     * Contents rendered in the diagnostics 
     */
    readonly contents: ReaonlyArray<DiagnosticPart>;

    /**
     * Command executed on click
     */
    readonly command: Command
}

interface CodeDiagnosticPart {
    readonly type: 'code';

    /**
     * Language to use for syntax highlighting
     */
    readonly language: string

    /**
     * Code rendered in the editor
     */
    readonly contents: ReaonlyArray<DiagnosticPart>;
}

• We could also use a more generic name like MessagePart (needs better name) so that parts could also be used in hovers and other UI locations

[mjbvz]

/cc @sandy081, @jrieken, @dbaeumer, @DanielRosenwasser, @weswigham, @amcasey

[amcasey]

FYI @minestarks

[weswigham]

Probably worth noting that for the syntax highlighting extension bit, it's very possible that syntax highlighted and linked/expanded ranges overlap; so them being mutually exclusive parts would seem to prevent that.

[mjbvz]

@weswigham Good point. I've updated CodeDiagnosticPart to potentially handle nesting better. One difficult thing about colorization is that the snippets may not actually be valid code. T<...> for example would colorize T as a variable.other.constant instead of as a type if we reused the js/ts grammar.

In the TS / editor sync today, we also discussed a proposal that would allow specific spans to marked as code or as expandable, something like:

interface DiagnosticMessage {
    /**
     * Text rendered in the editor
     */
    readonly text: string;

    /**
     * Ranges within the text that can be expanded.
     */
    readonly expandableRanges?: Range[];

    /**
     * Ranges within the text that should be rendered as code
     */
    readonly codeRanges?: { range: Range, language: string } [];
}

Keeping the range correct after expansion happens could get tricky

[jrieken]

Is this inventing our own markup language? How about using markdown as proposed by @mjbvz here:
#54272

[weswigham]

Rendered markdown could be used to implement hyperlinks (though you'd need to ensure file urls with locations work fine in markdown link tags) and if you're lucky syntax highlighting (although what's keeping the editor highlighting and the markdown highlighting consistent?) but I don't think it covers the expandable lazy ranges (the original request) - unless that markdown support goes all the way to full blown html/js support.

[weswigham]

It's might also worth noting that for the syntax highlighting part, we'd likely be trying to colorize things in specific contexts, so in addition to the standard markdown language selector, you'd also need to be able to somehow specify a specific tmLanguage rule to start in (instead of the root rule - this way our types get syntax highlighted as types and not statements). So in that regard, getting pre-classified spans (a la quickinfo) back from the language service might be easier than messing with picking apart tmLanguage rulesets; but I'm not the most familiar with them, so I'm not sure.

[jrieken]

unless that markdown support goes all the way to full blown html/js support.

Yeah, good point... We could experiment with commands. We already support command-links and we could have a special command that replaces the link text...

you'd also need to be able to somehow specify a specific tmLanguage rule to start in (instead of the root rule - this way our types get syntax highlighted

The markdown rendering picks up any language that's registered (by extensions). So it would require some special code-chunk-language so that MD will use the grammar that came with that language.

Stepping back a bit: The idea is to keep of all this in the editor hover, right? So make that smarter and a bit more interactive? I am asking because the hover is easy to dismiss and maybe not the best place for a UX in which the user invests time configuring its state.

[sandy081]

My 2 cents, I would not have asynchronosity in error message which might not have good UX especially in Hovers. Why does this needs to be async first of all Is it expensive to compute complete message?

Also not a big fan of having UI semantics. My first step would be to use MD string. BTW, Is not the related information can be used to show more information? I think we do not restrict this to be used only for multi-diagnostics but also for adding more information.

[weswigham]

Why does this needs to be async first of all Is it expensive to compute complete message?

It can be, yes. Our typesystem has the ability to generate new types by mapping old ones, so you can get very complex or large (anonymous) types with a very short sequence of type operators. And when those appear in errors, well... Things can get difficult to grok very quickly since there's simply too much to print - today we're forced to truncate the output, but making it explorable just like how dotting off the object can reveal more info would go a long way toward making it easier to work with.

My 2 cents, I would not have asynchronosity in error message which might not have good UX especially in Hovers.

Ignoring hover over red squiggles for a moment, errors still appear in the problems window and the f8 error bar as well, both of which are much more persistent. I'd think persisting the hover text as it is updated is an extension of those two.

BTW, Is not the related information can be used to show more information?

Nope - in this case the lazy querying is key to making it work. It allows us to gradually expose/generate the shape of complex types as requested, and only the parts requested. We actually have the ability to construct infinitely deep anonymous types - today we cut these off after printing one level of the type with a ..., but being able to expand these to an arbitrary depth as needed would be very nice. We do use related info where we can - it just doesn't help in complex type display/type truncation cases. (And secondarily would be a gratuitious way to "linkify" all the references in the types in an error, TBH - very nonlocal)

Stepping back a bit: The idea is to keep of all this in the editor hover, right? So make that smarter and a bit more interactive? I am asking because the hover is easy to dismiss and maybe not the best place for a UX in which the user invests time configuring its state.

What I was hoping was that diagnostic state was synchronized between the problems window/the f8 error bars/hover strings between full refreshes. That way you can expand within the hover if you want (then go back to it and still see it expanded), but also explore in the other places errors are displayed. In our meeting, someone mentioned that eclipse has the ability to copy things like individual diagnostics (plus stack traces and more) into a project context pane to allow them to persist and be inspected, which could work, too, but is maybe less continuous an experience than just being able to interact with a diagnostic anywhere you see it.