Summary

The current renderer for Guppy compiler diagnostics is written by hand and there are still many todos to handle edge cases (see for example #608). Instead of tackling all of those and maintaining our own renderer, it would be nicer to just hook into an existing solution.

We have identified the miette Rust crate as the ideal candidate: It offers fancy unicode rendering, colour support and lots of other stuff that we don't have yet. In short, the task is to create Python bindings to miette exporting the relevant functions to hook into Guppy's diagnostics system.

Details

Read our development guide to set up your environment: DEVELOPMENT.md

Guppy Diagnostics

Guppy's diagnostics system is defined in guppylang/diagnostics.py. Also see our diagnostics rendering tests.

Here is an example of how we currently render compiler diagnostics:

 Error: Short title for the diagnostic (at path/to/file.py:line:column)
   |
42 | def foo(x: blah) -> None:
   |            ^^^^ Primary label giving some source-dependent context
   |
55 |     x = bar() + baz
   |         ----- Sub-diagnostic label for additional context

Optional longer message describing the error.

note: Additional sub-diagnostic message without span

As seen above, we differentiate between the primary diagnostic pointing out the main error and optional sub-diagnostics that give additional context (either attached to some source span or a "note" or "help" at the bottom). The bindings to miette must be flexible enough to represent this level of information.

Miette bindings

The miette bindings should be built using PyO3/maturin and put into a top-level directory guppylang/miette-py. See guppylang/execute_llvm for another example of maturin bindings in the repo.

At least, the bindings will need to expose a Python class implementing miette's Diagnostic trait and the GraphicalReportHandler::render_report method. For now, it would be fine to use a GraphicalReportHandler with sensible defaults set in Rust, but ideally the bindings should also allow to customise rendering settings through Python.

Testing

Implement a function that turns a Guppy Diagnostic into an instance of the diagnostic class exposed from miette and add some tests to the tests/diagnostics directory following the existing diagnostics rendering snapshot tests.