Support multi-target references

[msujew]

Adds support for multi-target references. These are references that have the possibility to target multiple elements at once. See following illustration for an example:

Note that by default, only elements that are defined on the same scope can be targeted. I.e. a multi reference as in the following will only target one element:

This behavior can be freely overwritten by adopters of Langium. However, due to the inherent complexity of aligning the References service implementation and the scoping wrt their behavior, this feature is intended for proficient Langium developers.

The intended use cases for this feature are stuff like declaration merging in TypeScript or partial classes in C#.

Contains a bunch of breaking changes:

• The whole References interface now returns arrays instead of T | undefined.
• Every service/interface/class that works with Reference in a generic manner (linker mostly) now also works with MultiReference.
• LinkingError no longer inherits ReferenceInfo (which didn't make a lot of sense in the first place), but contains a info property.

[msujew]

cc @cdietrich since you were interested in this feature.

[Lotes]

Thanks, looks good, I like especially that one can now ask for an array and do not need to check for undefined when getting references :D.
All in all I added some code improvement suggestions.
I would suggest to wait for more feedback, since I am not so deep in this area of the code, yet.

[Lotes]

From the diff: I would prefer a !isLinkingError(refInfo). Looks more official.

[Lotes]

Can this line ever be reached? What do you think about assertUnreachable?

[Lotes]

Minor: I saw this double call several times now. Would it make sense to introduce something that addresses both?

[Lotes]

Or breaking the API by introducing isReference (for both; or isAnyReference), isSingleReference and isMultiReference

[spoenemann]

I think it should be possible to realize this in a way that most adopters of Langium won't notice a lot of changes. The actual core changes are not too large, and are mostly adding, but not changing API (we can try to add instead of change in a few more places). I'll have a more detailed look at this within the next two months.

[spoenemann]

There's a missing grammar validation: reference type (single or multi) matches declaration (or is consistent with other inferred occurrences).

[spoenemann]

Thanks! This validation should still be added: #1509 (review)

[spoenemann]

Now inconsistent usage of references are detected, but not the consistency of assignment vs. declaration:

interface Entity {
    name: string
    superType: @Entity
    features: Feature[]
}

Entity returns Entity:
    'entity' name=ID ('extends' superType=[+Entity:QualifiedName])? '{'
        (features+=Feature)*
    '}';

This should error because the declared property is a single-reference, but the assigned property is a multi-reference.

[cdietrich]

@msujew what was the reasoning behind exporting this one but not the one above

[msujew]

No particular reason, I thought it makes sense, and forgot that the other one isn't exported yet. Would you like to have both exported?

[cdietrich]

yes we are looking into writing linking traps and currently (3.5) we need to c&p everything