Semantic diff anyone?

Implementation details:

  • git diff accepts an arbitrary diff customization command
  • use refmt to turn the text into the ast
  • magic (hopefully not slow) ast diffing
  • use refmt to print it back into diff text for e.g. terminal viewing
  • bonus: time out with a good message if the diff takes more than a few seconds. I’ve had great but slow diff algs block the version control workflow. Not a good experience.

Been wanting this for a while now, but no time, and the implementations can be tricky to get right (ping me if you need help at any step ofc).

Credits to @sgrove for reminding me of this.


Then, once we have semantic diffing we can embed it in a publishing tool, diff the interface of the current code against the last published package, and use that to enforce semantic versioning.


OCaml already has semantic diffing at the module level, it’s how it statically enforces consistent linking of modules.

Because linking is resolved at compile time, SemVer is more of a ‘nice to have’ in OCaml rather than a ‘must-have’. At least, that’s the way I see it.

Also, a couple of things in OCaml today actually make it difficult to enforce SemVer. E.g., module type of in argument position of functors. See e.g.

In fact I think this is why Bob wants to remove module type of from BuckleScript altogether. Personally I won’t miss it, but that would make it more difficult to port arbitrary OCaml code to BuckleScript.


I think it’d be reasonable to follow semver with some basic assumtpions and exceptions, like assuming module type of is not used across packages, and the exception that opening modules may cause namespace collisions. Some guarantees are better than no guarantees, and semver is a betetr strating point than the wild west approach.

But even if enforcement is deemed a bit strong, a set of lints would still be very valuable. Like checking that no API has been removed without first being deprecated and only if it’s a major version bump.


Yup, definitely it would be nice. It’s just that we wouldn’t necessarily be at the mercy of package authors if they had an accident and mislabelled a version. We’d just get a nice compile failure when trying to upgrade instead of runtime errors. OCaml’s type system saves the day again!