Add ariadne wrapper `ToDiagnostic` / `CliReport`

[goto-bus-stop]

This is an attempt to provide a reusable API on top of ariadne that downstream users can use to get similar formatting to apollo-rs. There is especially a need for this as ariadne uses character indices while apollo-rs uses byte indices, so we need to convert the numbers in between.

This adds public API:

• ToDiagnostic::report(&mut CliReport) - a trait method that custom errors can implement to provide advanced diagnostics for printing to CLI
• CliReport - a builder for advanced diagnostics, provided to ToDiagnostic::report
• Diagnostic<T> - a wrapper for custom error types that provides pretty-printed fmt and io::Write output using the ToDiagnostic trait
• ResultExt::to_diagnostic(SourceMap) - extension method that wraps the error branch of a Result in a Diagnostic<>, so you don't need to do a verbose .map_err dance

This API requires that users store the error location inside their own error type.

Inconveniences:

• If you're using an error enum, you have to store the location in every branch, and match in your .to_report() implementation
• This does not include DiagnosticList, which may be useful, as collecting multiple errors is a common use case and having to write your own fmt impls and a custom wrapper type for Vec<YourError> is busy-work

The things to do here:

• [x] Maintain the color/no-color settings from main, this is why tests break at the moment
• I'd like to rework at least executable validation to use this similarly to how build errors use them -> moved https://github.com/apollographql/apollo-rs/issues/756
• Should we fit schema coordinate / operation expression based error locations in this somehow?
  • No, this API will not have schema coordinates at all. The diagnostics that use this API can have coordinates/paths/expressions, though.
• validate usability in a third-party crate; document happy path
• [x] Consider if we need to provide a JSON error conversion function

[SimonSapin]

https://github.com/apollographql/apollo-rs/pull/764 adds DiagnosticList::merge which internally merges two SourceMap. https://github.com/apollographql/apollo-rs/pull/764#discussion_r1410910183 points out that may be useful separately, but SourceMap is a type alias for foreign types so we can have an inherent method SourceMap::merge.

[goto-bus-stop]

This now always uses colors and strips them out at the end, because ariadne adds/strips colors as soon as you add a label, but here we would normally add the labels first and then decide whether they should be colored when it's time to print.

I added write and fmt inherent methods that consume self so we only need one type. You have to pass in a SourceMap in order to render, and you have to use the fmt method inside your own fmt::{Display,Debug} implementation, but you can't pass in a SourceMap into your own fmt::{Display,Debug} implementation except for having it available on the object. Soo yes this way would require exposing Diagnostic (and DiagnosticList probably) for people's custom errors, probably with a trait, which feels heavyweight, or expecting users to stick a SourceMap in their errors wherever they are produced. Will experiment with it a bit in fed-next :)

[goto-bus-stop]

Going to explore using the Diagnostic{sources, inner} type that we use with a generic inner error. You would have to wrap your error type with Diagnostic<> to print it with pretty formatting. One motivation for that is that inner errors would commonly derive thiserror, so they already have a fmt::Display implementation, and can't then also have pretty printing. (Unless users avoid thiserror and instead use DiagnosticReport, which would be less nice) The inner type would have to implement a trait method to produce a diagnostic report which Diagnostic::fmt would use.

[SimonSapin]

I made some tweaks, added a changelog, and merged to stop myself from making more tweaks :sweat_smile: