Add structured published diagnostics

[jvican]

Follow up of https://github.com/Microsoft/language-server-protocol/issues/510#issuecomment-401380425.

The idea is to enrich build/publishDiagnostics so that build tools/compilers/linters can feed in more structured data that can be processed/used in the client side. For example, a compiler could split up a normal error message in several fields (summary, long description, suggested fix/actionable message, link to docs) so that clients can better utilize this data in the UI side.

As a user, I'd like to have the following experience when reading diagnostics:

1. Summary is shown right next to the line the error is detected at (I think this is done via action/codeLens). Example:
2. The long description is shown whenever I hover over it.
3. If there's a doc attached to it, there will be a "See more" clickable link a the end of the hover tooltip so that I can browse the whole documentation page.
4. If there's a suggested fix/actionable message (either coming from the compiler or a linter), there will be a code action to apply it (textDocument/codeAction).

To be defined:

• Should we expose a new entry point for the new diagnostics or stick to build/publishDiagnostics? If we use the same, we need to support non-rich diagnostics in our richer encoding.

Design requirements:

• The interface for the messages should be as simple as possible and be mostly focused on compiler output. More complicated tools can use an extra field (typed as any) to add their format-dependent data if required.
• Allow the proposed "suggested fix/actionable message" field to be either a patch (.diff) or a full text message (an actionable suggestion could not be just code). Clients will handle this information as it suits them.

For a language server, the value of this integration is mostly in the suggested fixes/code actions coming from a build tool (no need to special case linters in the language servers). The language server can create a code action in the editor and apply patches that come from the linters set up in the build tool.

I believe language servers should be in charge of the state of diagnostics, so if we want to cover the developer experience described in this ticket we'll most likely need a way to pass in the "summary", "long description", "doc link" and "action" to the editor via LSP.

[jvican]

Note that this proposal would be blocked on LSP implementing the mentioned subset of rich diagnostics. There's little value in doing it on our own.

[olafurpg]

I propose to close this ticket for now and keep it in mind for the future in case LSP adds richer metadata to textDocument/publishDiagnostics. As it stands, it's unclear how many clients/servers/compilers are able to take advantage of the richer diagnostic structure. For example, scalac only reports message: String (no summary).

Note that LSP already supports "quick fixes" for published diagnostics via textDocument/codeAction. When the users cursor or mouse moves over a diagnostic the editor sends a codeAction request including the diagnostic at the active range https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction

[jastice]

Agree @olafurpg . Instead of closing I've added it to a backlog milestone