Parametric LSP: call hierarchy API

[toinehartman]

This PR designs and implements textDocument/prepareCallHierarchy, callHierarchy/incomingCalls, and callHierarchy/outgoingCalls for parametric language servers, allowing DSLs to implement call hierarchies.

data CallHierarchyItem
    = callItem(
        str name,
        DocumentSymbolKind kind,
        loc src,
        loc selection,
        set[DocumentSymbolTag] tags = {},
        str detail = "",
        CallHierarchyData \data = none()
    );

data CallHierarchyData = none();

Design

This design collapses the incoming/outgoing calls services into, since they are very similar. It also groups prepareCallHierarchy in the same constructor, since neither can exist without the other.

data LanguageService
    = callHierarchy (
        list[CallHierarchyItem] (Focus _focus) callableItem,
        lrel[CallHierarchyItem item, loc call] (CallHierarchyItem _ci, CallDirection _dir) calculateCalls)
    ;

data CallDirection
    = incoming()
    | outgoing()
    ;

Since a single cursor can produce multiple hierarchy items (e.g. in the case of overloads), and the implementer might want to influence the order, we require a list/lrel.

Alternatives considered

• A summary-based implementation, where we add information to Summary in an attempt to make call to the hierarchy services cheaper and simpler. This requries quite some additions to the summary, means that a hierarchy always requires a summary to be present, and additionally makes passing around the optional state (value data field) cumbersome.

An example of this implementation can be found here: https://github.com/SWAT-engineering/bird/blob/demo/call-hierarchy/bird-ide/src/main/rascal/lang/bird/LanguageServer.rsc

Closes #132

[DavyLandman]

I've written down some thoughts, let me know what you think.

[sungshik]

A small and a smaller comment.

[jurgenvinju]

IMHO it is essential for efficiency that we know in advance if we are looking for callers or callees.

• Callees have typically already been resolved by the static checker, and can probably be retrieved from a summary. This is because the checker knows everything about what is being used in the current module.
  • After retrieval from the summary optionally some static filter can be applied (by arity, static type of the parameters, etc)
• Callers require a reverse index and a "closed world assumption"
  • we need to know the callers of every other program/library in the {current workspace, current project, current ?}
  • that index must be reversed as a whole, and we can find the callers of our selected callee.
  • then the aforementioned static approximation filter must be applied (for example by arity or static type of the parameters, etc)

So those two are significantly different algorithms in general. If Bird accidentally does not make the same distinction, then that's an exception rather than a rule IMHO. Especially the "closed world" aspect has big impact on both usability (what else do you need it for?) and efficiency (Now we need up-to-date summaries of all possible caller files).

[jurgenvinju]

I'm worried that with the current setup DSL developers will need to re-invent their reverse modular indexing again and again for every language. At the same time we already have the Summary concept for indexing a single file, and summaries have been designed to be modularly composable. So we are pretty close...

Let's take a step back and see what that means in general, and if we can factor out that aspect in a language contribution by itself? Or perhaps a general feature.. I don't know.

[jurgenvinju]

Funny note: this indexing feature was why IBM was interested in vallang for making Eclipse more language parametric, called "Program Database" at the time. Vallang was then modelled after the Meta-Environment's "RScript" databases, and the ATerm library.

[DavyLandman]

Okay, I had a call with @jurgenvinju and we decided:

1. We want to add a "index" feature to our LSP abstraction, a bit like summaries but then linked. That index would help users implement call hierachy and other requests (such as references) a lot better. But that is not part of this PR, this PR is the "raw" mapping of the original request from LSP to Rascal, and leaves many of the heavy lifting on the semantics side to the end user
2. There will be a separate design for indexing, that will be more cross cutting, and will help DSL implementors "do the right thing"
3. we should improve the documentation of this (and also references) to try to sketch the semantics LSP expects from implementers.

[DavyLandman]

Just 2 small things, but this looks close to merging.

Also: please add an entry to the rascal-vscode-extension/CHANGELOG.md

[DavyLandman]

add a small comment on why this class exists, what its purpose is.

[DavyLandman]

if all these fields are used once, why are they in a separate static field? I do not see how that makes the code more readable? cons.get(NAME) vs cons.get("name")?

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.3% Duplication on New Code

See analysis details on SonarQube Cloud