Missing node

[sorawee]

Hi! I'm new to Langium, and I would like to know if there's a guideline on how to check for missing nodes.

I could do it in the ad-hoc manner, but it would be very easy to make mistakes and miss the checks. For example, even in the showcase (https://langium.org/showcase/arithmetics/), if you type b %;, you will get the error:

Line 14-14: Expecting: one of these possible Token sequences: 1. [(] 2. [NUMBER] 3. [ID] but found: ';'
Line 14-14: An error occurred during validation: Cannot read properties of undefined (reading '$document')

The second line is an internal error that is surely not meant to surface to users. The problem is that when we write validators, we usually assume that the AST is well-formed, but that assumption is wrong if there's a missing node.

More generally, I feel I have a fundamental misunderstanding of the Langium workflow. The text in the documentation says:

After resolving the cross-references, you can assume that the syntax tree is complete. Now you can start with the validation of the input files. The validation process is a crucial part of the language engineering workflow. The parser ensures the syntactic correctness of the input files. The validation process ensures the semantic correctness of the input files.

but this is clearly not the case, as the arithmetics showcase shows. The AST could be incomplete even in the validation phase.

Furthermore, the AST type definition generated by Langium is misleading. It makes it appear that the tree is always complete, when in fact, | undefined probably should be added everywhere.

Am I missing anything?

Thank you!

[msujew]

Hey @sorawee,

interestingly enough, I get a different set of errors when entering b %;:

Furthermore, the AST type definition generated by Langium is misleading. It makes it appear that the tree is always complete, when in fact, | undefined probably should be added everywhere.

It's kind of difficult to fulfill everyone's expectations with regards to what they expect of the generated AST definitions. I would argue that we do it "correctly" (whatever that means) as a syntactically correct input yields an exact instance of the types generated by the CLI. Invalid input will usually result in some form of malformed AST, but you only need to handle this in the scoping and validation infrastructure. If necessary, you can use a generic type that makes all AST node fields options. Something like Optional<T extends AstNode> = Partial<T> & AstNode. This will force you to handle the absence of a property explicitly.

Every step that works with an AST that has gone through a successful validation (i.e. for transpilation) is ensured to operate on a syntactically and semantically valid model. Therefore, using a type definition that reflects a valid input is pretty useful, at least for us.

[sorawee]

Interesting... this is what I got.

But "An error occurred during validation" doesn't sound like a user-facing error regardless.

If necessary, you can use a generic type that makes all AST node fields options. Something like Optional = Partial & AstNode. This will force you to handle the absence of a property explicitly.

I'll play around with this. Since this is a common pitfall, I think it would be really great to have a recipe that calls this problem out, and shows how to deal with it.

Thanks!

[msujew]

But "An error occurred during validation" doesn't sound like a user-facing error regardless.

No, it doesn't. The validation is definitely not written correctly. We expose the error to the user to ensure that the developer building a validation has a chance to catch the error in their language server. Otherwise it will just be silently swallowed.

[msujew]

@sorawee See also #1760 which aims to propose an improvement for this (and fixes the validation error as well).