bug#73452: Code lens support in eglot

bug#73452: Code lens support in eglot

[Federico Beffa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 648 bytes --]

Hi,

This is not a bug report, but rather an inquiry or feature request. I'm 
wondering if there are any plans for eglot to support code lens.

These provide quite useful functionality. For example, the Haskell 
language server allows putting expressions (typically for test or 
documentation) in comments with a special syntax. The server then offers 
to execute the code (in VSCode appearing as a small button above the 
expression). When pressed, it inserts the result in a comment just 
below. Here's an example after execution:

```haskell
addOne :: (Num a) => a -> a
addOne x = x + 1

-- >>> addOne 2
-- 3
```

Thanks for the great work!
Fede

[-- Attachment #2: Type: text/html, Size: 1038 bytes --]

bug#73452: Code lens support in eglot

[João Távora]

There is a discussion thread about this in the Eglot GitHub downstream tracker.

https://github.com/joaotavora/eglot/pull/71

The current consensus there is that the feature is not _that_ useful,
and that a clean implementation isn't really trivial since there is no
underlying Emcas support structure (like there is for documentation,
cross-referencing, diagnostics, snippets, etc)

João

On Tue, Sep 24, 2024 at 3:02 PM Federico Beffa
<federico.beffa@fbengineering.ch> wrote:
>
> Hi,
>
> This is not a bug report, but rather an inquiry or feature request. I'm wondering if there are any plans for eglot to support code lens.
>
> These provide quite useful functionality. For example, the Haskell language server allows putting expressions (typically for test or documentation) in comments with a special syntax. The server then offers to execute the code (in VSCode appearing as a small button above the expression). When pressed, it inserts the result in a comment just below. Here's an example after execution:
>
> ```haskell
> addOne :: (Num a) => a -> a
> addOne x = x + 1
>
> -- >>> addOne 2
> -- 3
> ```
>
> Thanks for the great work!
> Fede



-- 
João Távora

bug#73452: Code lens support in eglot

[Eli Zaretskii]

> Cc: 73452@debbugs.gnu.org
> From: João Távora <joaotavora@gmail.com>
> Date: Tue, 24 Sep 2024 15:26:55 +0100
> 
> There is a discussion thread about this in the Eglot GitHub downstream tracker.
> 
> https://github.com/joaotavora/eglot/pull/71
> 
> The current consensus there is that the feature is not _that_ useful,
> and that a clean implementation isn't really trivial since there is no
> underlying Emcas support structure (like there is for documentation,
> cross-referencing, diagnostics, snippets, etc)

What infrastructure would be needed?

Perhaps you or someone would like to describe the missing
infrastructure, and we could then at least add that to TODO.  And
maybe someone would even like to work on that.

Thanks.

bug#73452: Code lens support in eglot

[João Távora]

On Tue, Sep 24, 2024 at 4:48 PM Eli Zaretskii <eliz@gnu.org> wrote:
>
> > Cc: 73452@debbugs.gnu.org
> > From: João Távora <joaotavora@gmail.com>
> > Date: Tue, 24 Sep 2024 15:26:55 +0100
> >
> > There is a discussion thread about this in the Eglot GitHub downstream tracker.
> >
> > https://github.com/joaotavora/eglot/pull/71
> >
> > The current consensus there is that the feature is not _that_ useful,
> > and that a clean implementation isn't really trivial since there is no
> > underlying Emcas support structure (like there is for documentation,
> > cross-referencing, diagnostics, snippets, etc)
>
> What infrastructure would be needed?

It's not easy to describe, you'd have to be very familiar with how
code lens work on VSCode and Visual Studio (I'm not).  It's a cross
between Flymake and Eglot's custom inlay hints.

The lower-level infrastructure (buttons, overlays, jit-lock-register) exists
and is probably enough for a decent experience (though there are
the typical annoying flaws with overlays and jit-lock-register).  The problem
is knowing how to tie this together in an sensible and robust infrastructure
that Eglot (or other providers) can plug into.  An abstraction that will model
something presumably more useful and practical than what is already
available through other existing Emacs means (vc-* commands, M-x compile,
Eglot code actions).  Read the last parts of the discussion I linked
to if you're
interested.

João

bug#73452: Code lens support in eglot

[Federico Beffa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 484 bytes --]

That's an interesting conclusion, but it's up to the servers to decide 
how to provide the information. Imagine if a web browser implementor 
would decide not to support an HTML tag used by a non-negligible 
percentage of web pages.


On 24/09/2024 16:26, João Távora wrote:
> There is a discussion thread about this in the Eglot GitHub downstream tracker.
>
> https://github.com/joaotavora/eglot/pull/71
>
> The current consensus there is that the feature is not _that_ useful,...

[-- Attachment #2: Type: text/html, Size: 1066 bytes --]

bug#73452: Code lens support in eglot

[João Távora]

On Wed, Sep 25, 2024 at 8:04 AM Federico Beffa
<federico.beffa@fbengineering.ch> wrote:
>
> That's an interesting conclusion, but it's up to the servers to decide how to provide the information. Imagine if a web browser implementor would decide not to support an HTML tag used by a non-negligible percentage of web pages.

Alright, I imagined it. And I don't see the resemblance to this use case.

I'm not opposed to anyone implementing it, I just don't see a very interesting
cost/benefit.   And neither do some of the people who originally proposed it,
apparently.

João

bug#73452: Code lens support in eglot

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Tue, 24 Sep 2024 22:01:02 +0100
> Cc: federico.beffa@fbengineering.ch, 73452@debbugs.gnu.org
> 
> > What infrastructure would be needed?
> 
> It's not easy to describe, you'd have to be very familiar with how
> code lens work on VSCode and Visual Studio (I'm not).  It's a cross
> between Flymake and Eglot's custom inlay hints.
> 
> The lower-level infrastructure (buttons, overlays, jit-lock-register) exists
> and is probably enough for a decent experience (though there are
> the typical annoying flaws with overlays and jit-lock-register).  The problem
> is knowing how to tie this together in an sensible and robust infrastructure
> that Eglot (or other providers) can plug into.  An abstraction that will model
> something presumably more useful and practical than what is already
> available through other existing Emacs means (vc-* commands, M-x compile,
> Eglot code actions).

Then maybe someone could describe such an abstraction.

> Read the last parts of the discussion I linked to if you're
> interested.

I did, but couldn't answer my questions, because the discussion relies
heavily on VSCode features with which I'm not familiar and whose
descriptions I saw didn't clarify the issue.

bug#73452: Code lens support in eglot

[João Távora]

On Wed, Sep 25, 2024 at 12:31 PM Eli Zaretskii <eliz@gnu.org> wrote:

> Then maybe someone could describe such an abstraction.

Maybe.

> > Read the last parts of the discussion I linked to if you're
> > interested.
>
> I did, but couldn't answer my questions, because the discussion relies
> heavily on VSCode features with which I'm not familiar and whose
> descriptions I saw didn't clarify the issue.

Yes, that's part of the problem.  This LSP feature is a VSCode/VStudio MS
UI thing, and I also don't know those things well.  The few times I open
these apps I get turned off by all the clutter.

bug#73452: Code lens support in eglot

[Federico Beffa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 2662 bytes --]

On 26/09/2024 10:09, João Távora wrote:
> On Wed, Sep 25, 2024 at 12:31 PM Eli Zaretskii<eliz@gnu.org> wrote:
>
>> Then maybe someone could describe such an abstraction.
> Maybe.

Code lenses are not too different from code actions (see below). A new 
abstraction would make sense only if you plan to reorganize the entire 
`eglot` code. In that case the concept of a "code reviewer" or 
"assistant" could be useful, with functions like
- signal-error
- suggest
- exec-in-comment
- visit
- show-references
- show-type
...

>
>>> Read the last parts of the discussion I linked to if you're
>>> interested.
>> I did, but couldn't answer my questions, because the discussion relies
>> heavily on VSCode features with which I'm not familiar and whose
>> descriptions I saw didn't clarify the issue.
> Yes, that's part of the problem.  This LSP feature is a VSCode/VStudio MS
> UI thing, and I also don't know those things well.  The few times I open
> these apps I get turned off by all the clutter.

I'm not an expert, but my understanding is as follows:

A code lens represents a command that should be shown to users along 
with source code text, like the number of references, a way to run 
tests, etc. It goes like this:

1. The client sends a code lens request.
2. The server replies with commands along with the text to show to the user.
3. When/if the user chooses to run any of them, the client sends the 
request to run it to the server. (As an option it's also possible for 
the client to run the command.)
4. The server executes the command and replies with the change in the 
source code.

So, the main difference between code actions and code lens is the fact 
that the latter should show some text to the user. A few examples from 
the Haskell language server are:

- You can run some code in comments and get the result added. Here is a 
screenshot from VSCode

"Refresh..." is sent by the server. (It's "Execute..." before the first 
execution).

- An "import" lens suggests changing a library import to only import 
used symbols


- Expressions without type annotations get a lens showing the type and, 
if executed, it's added.


You may not like the VSCode UI, but Emacs doesn't have to use exactly 
the same interface. The client decides how to present the code lens 
text, and you may choose to only display it in some circumstances.

Code lenses are part of the core features of LSP since several years and 
are used by many servers. If Emacs ignores them, all those features are 
not available in Emacs. A client can't decide that it prefers to use 
actions instead of lenses. It's the server how decides how to offer the 
functionality.

[-- Attachment #2.1: Type: text/html, Size: 4267 bytes --]

[-- Attachment #2.2: 4xBEPkgoXUmaIYt5.png --]
[-- Type: image/png, Size: 8581 bytes --]

[-- Attachment #2.3: prAlDPTayQnnVXu0.png --]
[-- Type: image/png, Size: 22479 bytes --]

[-- Attachment #2.4: 3cw4R60JKTw4gJ80.png --]
[-- Type: image/png, Size: 32276 bytes --]

bug#73452: Code lens support in eglot

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 1699 bytes --]

On Thu, Sep 26, 2024 at 4:35 PM Federico Beffa <
federico.beffa@fbengineering.ch> wrote:

> You may not like the VSCode UI, but Emacs doesn't have to use exactly the
same interface. The client decides how to present the code lens text, and
you may choose to only display it in some circumstances.

Like Eli said: design and _fully_ specify a model of user interaction with
this feature and present it.
Doesn't have to be a funcional prototype, a mockup of some sort will do, as
long as it is specified enough for future implementers to understand edge
cases.

I.e. it's not enough to say "I want this thingy here like VSCode". Think
what happens if text  is inserted before, inside or after, the locus of the
"code lens" annotation (if any).  What happens if the text is deleted. What
conditions, if any, lead to invalidation of the lens's information and what
happens
on said information.  Anticipate the all-too-frequent "this thing flickers
and its
annoying" complaint and how to possibly deal with it. How it should work
(if
at all) in non-GUI Emacs.  All of that is work that needs to be done, you
don't
need to be an Emacs/Eglot wiz.  I personally don't see enough motivation to
do it.  I had for inlay hints, and I had to answer all those questions
before
implementing it.

> Code lenses are part of the core features of LSP since several years and
are used by many servers. If Emacs ignores them, all those features are not
available in Emacs.

From what I was able to gather from other's reports , these features are
already available
to users in one form or another.  Indeed, the examples you show here could
all be done
with code actions.

João

[-- Attachment #2: Type: text/html, Size: 2055 bytes --]

bug#73452: Code lens support in eglot

[Federico Beffa via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

On 26/09/2024 19:12, João Távora wrote:
> On Thu, Sep 26, 2024 at 4:35 PM Federico Beffa 
> <federico.beffa@fbengineering.ch> wrote:
> ...
> Indeed, the examples you show here could all be done
> with code actions.

You are right, but, as already mentioned, many language server 
implementors decided otherwise and that's not going to change because 
Emacs doesn't like code lenses.

Anyway, you made your point and that's fair enough.

[-- Attachment #2: Type: text/html, Size: 1180 bytes --]

bug#73452: Code lens support in eglot

[Dmitry Gutov]

Hi!

On 26/09/2024 22:07, Federico Beffa via Bug reports for GNU Emacs, the 
Swiss army knife of text editors wrote:
> You are right, but, as already mentioned, many language server 
> implementors decided otherwise and that's not going to change because 
> Emacs doesn't like code lenses.

I think the above would be a hasty conclusion: Emacs doesn't like or 
dislike them, but indeed we don't have an existing built-in UI to plug 
that feature in.

lsp-mode implements it with some custom code. Maybe we could do a 
similar thing as the first step for Eglot (someone will need to do the 
work, though), but of course it would be nice to make at least a part of 
the addition reusable.

bug#73452: Code lens support in eglot

[Dmitry Gutov]

On 25/09/2024 14:31, Eli Zaretskii wrote:
>> Read the last parts of the discussion I linked to if you're
>> interested.
> I did, but couldn't answer my questions, because the discussion relies
> heavily on VSCode features with which I'm not familiar and whose
> descriptions I saw didn't clarify the issue.

It seems to me that a brief description would be "buttons that do 
things", but unlike Code Actions - already available in Eglot - those 
things don't typically alter the text that they act on.

A LSP-generic mechanism to position those buttons at places in code 
which are recognized by the LSP server. For the LSP spec:

/**
  * A code lens represents a command that should be shown along with
  * source text, like the number of references, a way to run tests, etc.
  * ...

Running tests is the #1 use I found for them when writing some Go 
recently. Eglot doesn't have a built-in test launcher of any sort, so 
that feels like an omission.

There are other lenses for Go (enumerated here: 
https://go.googlesource.com/tools/+/master/gopls/doc/codelenses.md), and 
they do sound useful, but less essential in comparison.

And I would probably agree that the examples from the original PR are 
not that impressive (we already know how to search for references, and 
we know that that action works with every symbol - more or less, and we 
know how to access VC information - or in any case this would be the 
same across languages, or without LSP).

It seems the strongest point of code lenses is advertising actions 
specific to language and/or to a context within the source code file 
(such as, again, launching tests). So the user is made aware of the 
capability.

Admittedly, this seems more useful with some servers than others: gopls, 
rust-analyzer and ruby-lsp have test runner (and debugger) lenses, 
whereas clangd and typescript-language-server only have the "references" 
thing - I guess the usages count is nice, but it's much less essential.

bug#73452: Code lens support in eglot

[Eli Zaretskii]

> Date: Thu, 26 Sep 2024 17:35:21 +0200
> Cc: 73452@debbugs.gnu.org
> From: Federico Beffa <federico.beffa@fbengineering.ch>
> 
> Code lenses are not too different from code actions (see below). A new 
> abstraction would make sense only if you plan to reorganize the entire 
> `eglot` code. In that case the concept of a "code reviewer" or 
> "assistant" could be useful, with functions like
> - signal-error
> - suggest
> - exec-in-comment
> - visit
> - show-references
> - show-type
> ...
> 
> >
> >>> Read the last parts of the discussion I linked to if you're
> >>> interested.
> >> I did, but couldn't answer my questions, because the discussion relies
> >> heavily on VSCode features with which I'm not familiar and whose
> >> descriptions I saw didn't clarify the issue.
> > Yes, that's part of the problem.  This LSP feature is a VSCode/VStudio MS
> > UI thing, and I also don't know those things well.  The few times I open
> > these apps I get turned off by all the clutter.
> 
> I'm not an expert, but my understanding is as follows:
> 
> A code lens represents a command that should be shown to users along 
> with source code text, like the number of references, a way to run 
> tests, etc. It goes like this:
> 
> 1. The client sends a code lens request.
> 2. The server replies with commands along with the text to show to the user.
> 3. When/if the user chooses to run any of them, the client sends the 
> request to run it to the server. (As an option it's also possible for 
> the client to run the command.)
> 4. The server executes the command and replies with the change in the 
> source code.
> 
> So, the main difference between code actions and code lens is the fact 
> that the latter should show some text to the user. A few examples from 
> the Haskell language server are:
> 
> - You can run some code in comments and get the result added. Here is a 
> screenshot from VSCode
> 
> "Refresh..." is sent by the server. (It's "Execute..." before the first 
> execution).
> 
> - An "import" lens suggests changing a library import to only import 
> used symbols
> 
> 
> - Expressions without type annotations get a lens showing the type and, 
> if executed, it's added.
> 
> 
> You may not like the VSCode UI, but Emacs doesn't have to use exactly 
> the same interface. The client decides how to present the code lens 
> text, and you may choose to only display it in some circumstances.
> 
> Code lenses are part of the core features of LSP since several years and 
> are used by many servers. If Emacs ignores them, all those features are 
> not available in Emacs. A client can't decide that it prefers to use 
> actions instead of lenses. It's the server how decides how to offer the 
> functionality.

Thanks.  So basically, code lenses are suggestions for actions, and
those suggestions are presented as a kind of overlays over the code?

If so, I think the infrastructure we need is mostly the presentation
of the lenses and how the users select the action(s) they want?

bug#73452: Code lens support in eglot

[Eli Zaretskii]

> Date: Fri, 27 Sep 2024 03:20:35 +0300
> Cc: 73452@debbugs.gnu.org, federico.beffa@fbengineering.ch
> From: Dmitry Gutov <dmitry@gutov.dev>
> 
> It seems to me that a brief description would be "buttons that do 
> things", but unlike Code Actions - already available in Eglot - those 
> things don't typically alter the text that they act on.

This seems to be in contradiction with what's been said previously
(and my understanding from reading the linked pages): that code lenses
are UI sugar for server actions.  (If this is different from "Code
Actions", then I guess there's some subtlety here I don't get yet.)
You yourself say later that "the strongest point of code lenses is
advertising actions specific to language and/or to a context", which
seems to affirm my understanding.  And since Eglot already supports
actions, what seems to be missing is that UI sugar, i.e. a way of
presenting the lenses and a way for the user to select those he/she
wants to invoke.

bug#73452: Code lens support in eglot

[Dmitry Gutov]

On 27/09/2024 09:53, Eli Zaretskii wrote:
>> Date: Fri, 27 Sep 2024 03:20:35 +0300
>> Cc: 73452@debbugs.gnu.org, federico.beffa@fbengineering.ch
>> From: Dmitry Gutov <dmitry@gutov.dev>
>>
>> It seems to me that a brief description would be "buttons that do
>> things", but unlike Code Actions - already available in Eglot - those
>> things don't typically alter the text that they act on.
> 
> This seems to be in contradiction with what's been said previously
> (and my understanding from reading the linked pages): that code lenses
> are UI sugar for server actions.

There is no such term as "server action" in LSP, so the above statement 
is probably both true and false at the same time. But lenses are not 
sugar on top of code actions, if that's what you means.

 > (If this is different from "Code> Actions", then I guess there's some 
subtlety here I don't get yet.)

They are different parts of the LSP protocol, even though, practically, 
some "actions" could be implemented as either. Anyway to quote from 
https://go.googlesource.com/tools/+/master/gopls/doc/features/transformation.md:

   A code action is an action associated with a portion of the file. Each
   time the selection changes, a typical client makes a textDocument/
   codeAction request for the set of available actions, then updates its
   UI elements (menus, icons, tooltips) to reflect them. The VS Code
   manual describes code actions as “Quick fixes + Refactorings”.

   A codeAction request delivers the menu, so to speak, but it does not
   order the meal. Once the user chooses an action, one of two things
   happens. In trivial cases, the action itself contains an edit that the
   client can directly apply to the file. But in most cases the action
   contains a command, similar to the command associated with a code
   lens.

   ...

   The main difference between code lenses and code actions is this:

   * a codeLens request obtains commands for the entire file. Each
   command specifies its applicable source range, and typically appears
   as an annotation on that source range.
   * a codeAction request obtains commands only for a particular range:
   the current selection. All the commands are presented together in a
   menu at that location.

To give a couple of example: 'rename' is a code action, whereas 'run the 
test near point' is a code lens. Because the server will tell you which 
tests are defined in the current file and at which positions.

> You yourself say later that "the strongest point of code lenses is
> advertising actions specific to language and/or to a context", which
> seems to affirm my understanding.  And since Eglot already supports
> actions, what seems to be missing is that UI sugar, i.e. a way of
> presenting the lenses and a way for the user to select those he/she
> wants to invoke.

Yes, and what might be missing is not really a UI feature (we know how 
to print buttons, after all), but higher-level decisions, I guess, for 
how and when to print such buttons. It shouldn't be very difficult to 
implement, but people might disagree on the finer details of behavior.