Skip to content

compute: add another output command that exposes more metadata

Administrator requested to merge rvt/compute-w-meta into main

Created by: rvantonder

This implements a output.extra(...) command on compute queries which can serve purposes where more contextual data is needed from results (Repo metadata, etc.). Open to other name suggestions beside extra, but this seems good enough. This is a follow up to help resolve needs from https://github.com/sourcegraph/sourcegraph/pull/37952

The need for a separate command is for compartmentalizing concerns, where those concerns are very likely to change over time for an API that should be considered unstable. Those concrete concerns are:

  • output(...) right is minimal (exposes only kind and value). This is desirable and sufficient for many applications, where more metadata does not need to be in the resulting JSON.

  • output.extra(...) current exposes repo metadata, for a use case that benefits from it. It could expose any other data too. It should be kept separate because:

    • this metadata will be sent unconditionally, there is no GQL or REST-like query to request only certain fields here. Implementing such a thing right now is not an appropriate use of time, because we don't know what that would like yet. On the other hand, adding a little command to iterate against is lightweight, easy to remove, and can be modified for whatever application with minimal impact to existing implementation.

    • this metadata may not apply to opaque result values appropriate for output(...). Rather than creating an implementation need that might need to distinguish this on a single Text result type and optionally populate field, it's in my opionion better to just make that situation impossible and create a separate result type for this need.

Taking the above, consider the opposite, that we just populate whatever metadata in the output field. What I anticipate happening is that clients start to rely on this behavior and it becomes impossible to undo the bloating/metadata additions from output(...) when that becomes a problem in other contexts. Then to get back the minimal, opaque result type will then need "something else" + migration. Maybe output2(...). Maybe package compute2. And that, friends, is how you end up with File2 (I'm told the name will change soon 🙂 ).

Test plan

Added tests.

Merge request reports