It is my pleasure to announce the initial release of Grace, a cutting-edge OCaml library that includes a series of interfaces for building, reporting, and rendering beautiful compiler diagnostics.
To get started, simply run:
opam update
opam install grace
Key features
Inline and multi-line error messages with associated priorities
Multi-file errors
Configurable rendering (styling and character set)
Coloured messages for ANSI terminals
100% OCaml
The project is still in its early phase with many additional features planned:
Unicode support
LSP integration with linol
Accessibility features such improved colour options and narratable renderers
I invite the community to play with Grace, exploring its capabilities and limitations. Your insights will play a crucial role in shaping the future of this library
The short answer is that it is a non-trivial amount of work (in particular, making good use of the capabilities of the library probably requires domain-specific work to compute different information at the point each error is computed), no one is actively working on it, and there is some preliminary work by @Octachron on error messages that would help or possibly be necessary.
The bulk of the compiler work on error messages comes from @Octachron and myself. One problem is that we tend to be too busy with release-management and PR reviews/triaging to free time to make good progress on this – there is always something more urgent that comes up, and it is hard to prioritize. We also have infrequent but nice contributions from other contributors (Julow, hhugo, smuenzel). It might be that we could make progress with some dedicated organization, just like we do for type-system changes, release management, triaging, etc.
Here is a brief comparison after quickly looking at the Asai docs:
Both projects are diagnostic libraries, designed to assist in identifying and reporting issues within code.
Both libraries roughly have the same types for diagnostics, however, Grace has a slightly richer API with labels and priorities, providing more control on what context is added.
Renderers:
Asai has a simple ANSI renderer and a GitHub action renderer.
Grace, on the other hand, provides a complex ANSI renderer that supports Rust-style ASCII art error messages.
Unicode support:
Asai handles unicode in sources, accommodating a broader range of characters in rendered errors
Grace doesn’t currently support unicode, but aims to handle unicode characters in future.
Reporters/constructing diagnostics
Asai stands out by providing reporters for constructing diagnostics using algebraic effects.
Both libraries are rather opinionated, with Grace using JaneStreet’s core as a standard library replacement (although this will change in the future) and Asai extensively using algebraic effects.
Is it just me, or are ASCII art error messages a bit too distracting? I need error messages laid out in such a way that I can scan them quickly. Ideally, being parsimonious with extraneous wording, and taking advantage of indentation to show me the structure of an error. Seems I am against the current trend.
Thanks for the comparison! I had been looking at adding diagnostics to a tool I’m working on (https://discuss.ocaml.org/t/ocaml-is-awesome/13700). So Asai uses algebraic effects, which I can’t use because I’m stuck on OCaml 4 (and I need Windows). I tried installing Grace but as you mentioned it depends on core … the problematic dependency for me at the moment is core_unix which is not available on Windows.
I will take a look at Grace (not now though) to see how tightly coupled it is to core_unix.
As an alternative for people wanting a more minimal solution, I released pp_loc a while ago, which basically extracts the message highlighting code from the ocaml compiler (>=4.08) as a separate library.
Grace can absolutely be made more portable. core_unix was only used for Bigstring_unix which provides mmap’d big strings for opened files. I’ll open an issue for this
I also occasionally find Rust’s error messages a bit too distracting. My goal for Grace isn’t only to permit a single style of error, but to have multiple configurable renders. The error format can then be configured by the user for their own preference / use cases.
I am happy to see that @Alistair made the initial release! As the main developer of asai, I can comment that both libraries separate the generation and rendering of diagnostics, so one can easily mix and match (modulo the small difference in our representations of diagnostics). We are implementing helper functions to make the combining of the two libraries trivial. The progress to use Grace to render diagnostics generated by asai is tracked by the GitHub issue 💅 Implement a handler based on grace · Issue #107 · RedPRL/asai · GitHub. We are interested in working with @Alistair to get the other direction done as well.
We implemented the mmap trick directly in the asai codebase. We don’t want to include the mmap code in our library, but we also could not find a small library to save it. (Please let us know if we missed a good option.)
One more comment: the difference between our diagnostic types is a reflection of the difference between LSP and Rust, the two major camps. asai mostly follows LSP and Grace mostly follows Rust. For most cases, it should be possible to convert diagnostics back and forth without losing much information.
that includes a series of interfaces for building, reporting, and rendering beautiful compiler diagnostics.
Inline and multi-line error messages with associated priorities
Multi-file errors
Configurable rendering (styling and character set)
Coloured messages for ANSI terminals
100% OCaml
Unicode support
LSP integration with 
Accessibility features such improved colour options and narratable renderers
