[Proposal] Pipeline hints

[KennethHoff]

Pipeline hints

Problem

F#, and I'm sure other languages, heavily utilizes pipelining/chaining of function calls. Such pipelines can at times make knowing types quite difficult, particularly if you're unfamiliar with the domain.

F#

let input = System.IO.File.ReadAllLines("day1.txt")

input
|> Array.map Utils.splitStringIntoPair
|> Array.map Utils.convertStringPairToIntPair
|> Array.unzip
|> Utils.sortTupleElements
|-> Array.zip
|> Array.map Utils.abs
|> Array.sum
|> Taps.logAndContinue "Part 1: %d"

Fluent APIs have become much more common lately, with things like Zod being used in the JavaScript ecosystem for typesafe validation, and ASP.Net Core utilizing it heavily with their entrypoint file, the need for IntelliSense on these implicit return types are becoming increasingly more common.

C#

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services
    .AddSingleton<TimeProvider>(TimeProvider.System)
    .AddScoped<IPersonService, PersonService>()

WebApplication app = builder.Build();

app
    .MapGet("/api/person/{id}" (Guid id) => { /* Logic here */  })
    .WithDescription("Retrieves the person with the given id")

app.Run();

Proposal

I'm suggesting a new request designed to highlight return types of function calls whose values are implicitly passed to another function. This will help solve both of the previous problem statements.

I am not well versed enough in the intricate details of the LSP request specification to come up with anything more detailed than these visual examples, so at the moment I'm mostly interrested in starting a discussion; The request specification can come at a later date.

(Imagine that the code in the comments are the hints provided by the LSP, and not code comments)

F#

let input = System.IO.File.ReadAllLines("day1.txt")

input
|> Array.map Utils.splitStringIntoPair // (string * string) array
|> Array.map Utils.convertStringPairToIntPair // (int * int) array
|> Array.unzip // (int array) * (int array)
|> Utils.sortTupleElements // (int array) * (int array)
|-> Array.zip // (int * int) array
|> Array.map Utils.abs // int array
|> Array.sum // int
|> Taps.logAndContinue "Part 1: %d" // int

C#

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services
    .AddSingleton<TimeProvider>(TimeProvider.System) // IServiceCollection
    .AddScoped<IPersonService, PersonService>() // IServiceCollection

WebApplication app = builder.Build();

app
    .MapGet("/api/person/{id}" (Guid id) => { /* Logic here */  }) // RouteHandlerBuilder
    .WithDescription("Retrieves the person with the given id") // RouteHandlerBuilder

app.Run();

Alternatives

Extend the existing inlayHints request instead of creating a new one. This has the advantage of not requiring an entirely new request type, but the downside of polluting the inlayHints request, as well as any possible breaking changes to make it more ergonomic for this need.

Potentially relevant information

The naming is based off of Ionide (The F# LSP), which has their own custom fsharp-specific request with the same name, and has implemented it in their Visual Studio Code Plugin, but has not done so in their Neovim plugin, due to lack of support in Neovim.

[HighCommander4]

rust-analyzer supports this today, using inlay hints. Here is an example:

Doing it this way doesn't really require a protocol extension; while the protocol defines an InlayHintKind enum with two values (Type and Parameter), neither of which are applicable here, the kind field of InlayHint in the protocol is optional, which seems to give license to servers to send inlay hints of other kinds.

(Clangd is another server that supports inlay hint kinds beyond the two defined in the protocol, though pipeline hints are not one of them at this time.)

[KennethHoff]

I did not realize InlayHintKind existed; That changes things. It does sound like that should be extended in favor of adding a new request type type that is essentially the same thing.

The concept is very similar to a type hint, so much so that one could argue it should use InlayHintKind.Type already, but it probably shouldn't as it's presumably not designed for this use-case.

Adding a InlayHintKind.Pipeline ( name TBD) would therefore seemingly be a much better alternative than an entirely new request type.

[henryxparker]

@KennethHoff @HighCommander4 I would like to revive this discussion because I have a wrench to throw in it.
Behold:

Block justified pipeline hints!

I am here because I was in the middle of implementing this feature into metals, the scala LSP. I wanted to implement it in the same way that IntelliJ does it (pictured above), because when there are other inlay hint types being displayed at the same time, it can get very cluttered.

But when I included a position in the InlayHint that was past the text on the line, it simply put it at the end of the line, like the rust-analyzer example. So I did what anyone would do to get the feature out the door and included a bunch of spaces to justify the hints manually, but I dislike this implementation because it introduces complexity, the spaces are highlighted like the hint, and it is admittedly buggy. So finally I decided to look into the spec and realized there's no official support, and there are some under-documented parts (like paddingLeft). So here is my argument for why this should be part of the spec:

First off, the name "inlay hints" indicates that these will be sprinkled inbetween code, one could say, inlayed throughout. These pipeline hints are always at the end of a line. That means that the character part of the position is mostly irrelevant, unless it is going to be repurposed into allowing column values exceeding the end of a given line, and let me personally tell you that that would break a pretty major assumption that most LSPs probably make. (Metals certainly does)

Second, inlay hints tend to be very local. I can usually procedurally go through the code expression-by-expression and add inlay hints without considering much of the surrounding code if any. Even more important, these inlay hints are there regardless of formatting, but since pipeline hints are max one-per-line, formatting is important. I'm just a one-time contributor to an LSP at this point, but I would want that code to live in a different place.

Third, some LSPs may want these hints to be right-justified instead of block justified like my example. Perhaps the editor has a max-column-width and the inlay hints would appear just before(or even just after) this limit. That, to me, feels like an editor configuration option, not an LSP-specific configuration option. All the LSP needs to tell you is what line the pipeline hint is on (and maybe the span of lines taken up for multi-line pipes in a single block) and the editor will be able to configure where they appear without needing to know any syntax. For the IntelliJ example above they just need to know the column index of the longest line in the block, and not even that if they are right-justified.

Fourth, this could be repurposed for repl-specific LSPs. Scala has a special worksheet file type that functions like a repl, and currently the output of each line is just appended as a comment (ew), but if this became part of the spec it could be reused to display a nice right-justified output. Idk if any other languages have a similar thing, except maybe python notebooks which are waaaay more complicated, but I think people will find ways to use this feature well.

Fifth, If it's implemented in the editors I don't have to do as much work. Oh wait I wasn't supposed to say that part out loud.