Rust: Diagnostics Revamp Roadmap

[oli-obk]

The current diagnostics APIs are very unergonomic and can result in various verbose, repetitive and annoying code snippets.

cc @estebank

• [ ] Ensure that diagnostics have been emitted at compile-time (must-use and consuming emit method
• [ ] Improve/expand --teach API
  
  
  
  • Applicable to user code -> show hints for user code
  
  
  • else -> show hints for error code example
  
  
• [ ] Diagnostics builder API
  
  
  
  • use https://github.com/rust-lang/annotate-snippets-rs/
  
  
  • One struct per error (maybe too verbose) #61132
  
  
  • templates (maybe too many "special" cases)
  
  
  • real builder pattern
    
    
    
    
    
    • sub-builders for suggestions, ...
    
    
    
    • typesafe snippet to suggestion path
    
    
    
  
  
• [ ] Emitter API
  
  
  
  • allow builder API to set span labels in subdiagnostics
  
  
  • multiple spans in a subdiagnostic
  
  
  • suggestions and notes in arbitrary order
  
  
  • terminal width support
  
  
  • (windows only) background color check
  
  

[GuillaumeGomez]

Just when I added support for the current API in rustdoc... 😢

[estebank]

Just think about how much better things will be!

[csmoe]

I think the way to introduce next generation systems like chalk for trait-sys and polonius for borrowck is a great model of upgrading: create a independent crate then port into rustc, this will be easier for the future diag-api ‘s self-updating and more friendly to downstream tools like rustdoc,rustfix.

[oli-obk]

That... is an absolutely awesome idea.

We can totally recreate the diagnostics API in an external crate. Even better: we can also do that for the diagnostics emitter!

[euclio]

Factoring out the diagnostics emitter has a real use-case in cargo. There have been a few attempts at making a nicer build progress bar (https://github.com/rust-lang/cargo/pull/3451, https://github.com/rust-lang/cargo/pull/5620), but issues like https://github.com/rust-lang/cargo/issues/5695 prevent the feature from being a nice user experience: the progress bar output gets interleaved with rustc output. This could be fixed if cargo were able to capture output from rustc and print it itself, but as it stands, cargo cannot capture output from rustc without losing formatting.

However, if the diagnostics emitter were factored out into a third-party crate, it might be possible for cargo to recreate the errors and output them with full formatting.

cc @alexcrichton

[estebank]

@euclio that would require rustc to produce enough metadata to recreate the exact output (which I believe it is not possible at the moment, the json output is _slightly_ lossy). That doesn't mean it's not a worthwhile objective to aim for.

[nikomatsakis]

Over on Zulip we were recently discussing the idea of having a fallback "footnote" mode to use for overlapping, adjacent, or malordered labels. I wrote up the idea in this gist:

https://gist.github.com/nikomatsakis/80866d4407f1cc38fba0c2da7175dcf7

Example might be like:

15 |     };
   |     - (1)
   |      - (2)
   |
   | 1: `heap_ref` dropped here while still borrowed
   | 2: borrowed value needs to live until here

instead of

15 |     };
   |     -- borrowed value needs to live until here
   |     |
   |     `heap_ref` dropped here while still borrowed

(The proposal also includes a way to indicate labels that have an "ordering" to them that you would like the renderer to enforce.)

[Centril]

Does the WG have any plans for internationalization support?

[estebank]

We haven't discussed it but I feel that at this point we won't be able to maintain the level of quality we want while also scaffolding i10n support. I would love to hear others opinions.

Cc @rust-lang/wg-diagnostics

[Centril]

I think extracting diagnostics logic to structs and such is a great move for internationalization. Beyond that, the only think I would suggest is that you consider what i10n support in the future might take and try to avoid doing things that would make i10n harder in the future. Perhaps consider future-proofing traits and such today if possible.

[Manishearth]

We discussed i18n in the wg-diagnostics Zulip channel.

It becomes quite easy to migrate if we use a custom derive (or other plugin) to autogenerate AsError impls for diagnostics structs. We should start looking into getting that derive working and convert diagnostics to it.

Once a significant portion of the codebase is using AsError, we can start playing with Fluent.