Provide simple yaml-based output for release summary in runoak diff

[matentzn]

In Mondo (and similarly in HPO) we have

reports/difference_release_base.md: tmp/mondo-released.obo $(KGCL_ONTOLOGY)
	runoak -i simpleobo:tmp/mondo-released.obo diff -X simpleobo:$(KGCL_ONTOLOGY) -o $@ --output-type md

to generate a nice diff output with collapsible section. In both Mondo and HPO, we always have to hack the output to make it look like we want:

1. Change headings (e.g. New Disease Terms or similar, custom, custom)
2. Reorder sections (e.g. Additions first, removals last, etc)
3. Remove certain sections (e.g. we don't want to include changed definitions)
4. Prune certain sections (e.g. sometimes sections become too long, then we only provide a few examples and say "et al"

It would be great if we could:

1. Get a simple YAML based output of the release diff that is isomorphic to the current MD output produced by the command above
2. ... so that we can define a little jinja template to customise how we wish to present the diff in markdown

Unfortunately I personally don't have the resources to do this and we lack developer capacity right now, but I wanted to create the issue so it can be bumped in the future when the urgency increases.

[cmungall]

The option to emit markdown in diff is a bit quirky.

What is it that is incomplete about the current YAML output of diff (which follows the KGCL schema)?

As far as I can tell what you need is:

• grouping and ordering by change type
• injection of labels for referenced identifiers

These are very generic operations and it should be easy to add this an alternative output.

However, rather than proliferating new formats, I would suggest one of two approaches

1. Use jinja as you suggest, and pass in the existing change objects as well as a labelify function (that calls adapter.label). This is a standard pattern. See the linkml docgen templates for examples. No new formats are needed here. You have full control over everything in the jinja. You can sort, group by, and filter in jinja, no need for new formats. There is some repetition and boilerplate, but not too bad
2. Do this completely generically using existing capabilities. I believe the existing output is essentially taking change objects, sorting them, filtering them, tableifying (standard linkml), injecting labels (e.g. using FillTable). Some semi-bespoke code for breaking the table by a column value (change type).

I like 2 because it is generic can be applied to all kinds of OAK commands with minimal customization. However it is more abstract and harder to customize. For your use case, I would lean towards 1, and accept a bit of repetition in the jinja.