intuition for `flushDiagnosticsBySource`

[MangoIV]

Hi. I wonder three things:

• when is it ever useful to flush everything by source, disregarding the uri? I feel like this would really hurt incrementality. If I wanted to opt in to this, then at least the second stage of the map, that contain keys by uri should be part of the source, right? so that I can just flush by source whenever I don't specify an uri? otherwise, if I do want to flush source and uri, I need to key by source and uri and then the next stage would only be a singleton map.
• why is the source used as an internal criterium to store the diagnostics? Shouldn't this be unrelated to what is eventually displayed by the user? e.g. if I have several actual sources of a single diagnostic, then I want to still summarize it to the user as "this comes from the typechecker". It seems counterproductive to me to either having to maintain my own state around diagnostics and/or structure my program to have only one place of where diagnostics are emitted.
• are the means to flush a single diagnostic just "not yet" implemented or are they intentionally missing?

After reading the code I also don't quite understand if the current API is ever useful, if not intuitively, at least performance wise. Most of the operations require multiple traversals.

To summarize, I think I would expected the following API:

flushDiagsByDiagnosticsKey :: diagKey -> m ()
and then
Map diagKey [Diagnostic]

[MangoIV]

This is also unintuitive from an LSP perspective. I think what the spec intends for sources is that a single language server only makes one source. Why would I have a store for multiple sources giving me the overhead of a lookup for the eventuality that someone is implementing an n-in-1 language server or abuses the spec? In that case I would expect that they could implement the store themselves...

[michaelpj]

To be honest, I've never understood what this is for either.