Definition Diff machinery

[ChrisPenner]

Overview

We've long wanted to be able to diff definitions against each other.

Adding this machinery here so it can be shared between Share and UCM; but initial plan is to implement Contribution diffs first, then probably add them to Unison Local.

Implementation notes

Uses the Haskell Diff library to compute a diff over syntax text. This means we diff definitions at the semantic token level rather than just over plain-text, which has the benefit that we can still generate links, hovers, cool colors, etc. in the diffs when rendered in the browser.

It also allows us to easily detect and special-case:

• When a name changed, but the hash didn't
• When a hash changed, but the name didn't

We may still want full tree-based structural diffing, but I suspect this form of smart diff will last us a long time.

Test coverage

I have some transcript tests in Share, but this format is still experimental (I'm planning on shipping a version of this for Simon to play with, then will tweak as needed). It doesn't affect any existing UCM behaviour or features, nor is this change observable from the CLI at all.

Loose ends

We need a UI for it! Coming soon™

[aryairani]

@ChrisPenner Sweet!

[aryairani]

@ChrisPenner Are there some tests and/or demonstrations we can do on this side?

[ChrisPenner]

@aryairani Okay I added the actual Unison Local API and some transcripts for this in #4964 , let me know if that helps, or if there's anything else we need to get this merged in 🙌🏼

[aryairani]

Chris and I talked through the testing strategy and landed on a combination of

• it's not very practical to demo in the unison repo
• there are transcript tests on the Share side (and also for Unison Local now, with Unison local Definition Diffs API #4964), but the output is hard for a human to interpret, so we kind of need a UI to help with that; the format may also change based on newly discovered requirements during development of the UI
• we could create a ucm debug command to render diffs (and we may still end up wanting to do this), but it would be easiest for it to use colors (vs additional characters) to display diffs, and the colors wouldn't show up in transcripts, so we would be looking at test screenshots at best.
  • side note: a transcript runner that produced HTML output sounds awesome imo discussed this and decided it didn't sound awesome
• the actual diffing is done in the Diff library https://hackage.haskell.org/package/Diff

transcript output mismatch