realworldocaml / mdx

Execute code blocks inside your documentation
ISC License
265 stars 45 forks source link

Report all syntax errors in Markdown files #389

Closed NathanReb closed 2 years ago

NathanReb commented 2 years ago

This PR improves the MDX workflow by making sure that all parsing errors are reported at once rather than exiting on the first errors.

Obviously that only impacts errors that we can recover from e.g. mis-used or missing labels, syntax error inside a block but not for errors such as invalid markdown.

We used to do all the work in markdown/cram parser. I changed that to extract raw bits of data from the parser and leave their interpretation to a later pass.

While working on this I discovered that the locations we attach to blocks are incorrect due to inconsistencies in eol handling in the lexer code which I took the liberty to fix as part of this PR. I can eventually extract it as a separate PR depending on this one if you'd like but basing it on this work made it significantly simpler.

NathanReb commented 2 years ago

There is a small side effect which is that errors with labels are reported with the entire block location. I think it's not too bad, especially given how precise the error messages usually are, there should be no ambiguity as to where the error comes from.

We can eventually try to refine error locations even further but since we have no editor integration at the moment I see little incentive for it.

NathanReb commented 2 years ago

Finally, this does not impact mli files at the moment. The implementation of the parsing being quite different I decided to open a PR with I already had.

I'll work on the mli side of things next but doing it separately should ease the review!