Codebase Server API: Definition summaries

[hojberg]

We want to support a notion of a definition summary and source summary which is more compact response than the /getDefintion result.

This ticket will support and unblock these UI tickets:

• https://github.com/unisonweb/codebase-ui/issues/112
• https://github.com/unisonweb/codebase-ui/issues/157
• https://github.com/unisonweb/ui-core/issues/22

Suggested response schema

A DefinitionSourceSummary is defined is defined as such:

• Types: up until the =: type List a
• Abilities: up until where: ability IO
• Terms: the term signature: Char -> Text -> [Text] without the name of the term (example is Text.split).

We should support these for all definitions, including builtins (which might be a challenge for types, though we can at least do type List)

DefinitionSourceSummary will be used in several endpoints:

• The sourceSummary field replaces the termType and typeDef fields of the /find endpoint,
• The sourceSummary field replaces the signature field of /getDefinition for terms
• The sourceSummary field is added to /getDefinition for types
• A new /definitionSummary endpoint which includes a the same response shape as /find, but for a single definition which can be queried by hash or name—used for hovering references.

[hojberg]

To the last point about the new /definitionSummary endpoint:

There's an other option to allow hovers on references in source to get the type of them in a tooltip and that is to embed that in the original source. The benefits of this is that we don't have to do an ad-hoc Ajax request on hover and also this opens up the door for a more uniform representation of hovers—we'd eventually want to allow hover on non-references as well such that you can get the type of a sub expression (@rlmark brought up this kind of UX after our last Wednesday hack day)

The major downsides to embedding summaries is performance and download size. Perhaps there's an in-between that allows for both where we can do ad-hoc queries for types of sub-expressions in some way?

cc @pchiusano @runarorama