Debug tool idea: cue explain

[cueckoo]

Originally opened by @vikstrous2 in cuelang/cue#927

After having spent some time using CUE, I think back to when I was comparing CUE and cdk8s one of their major selling points was auto-completion and go to definition in the editor (normal programming language features). I thought that the simplicity of CUE would remove the need for this and the fact that it's not a traditional programming language would make these features obsolete, but I'm starting to feel like there's something important missing in CUE. This is essentially debuggability.

In a normal programming language, you can put in print statements. You can use go to definition. You can use auto-complete. You can use a debugger. In CUE, none of this is possible, so the only way to debug a CUE config issue is to diff the output or to delete code (let's just call CUE config "code" in the general sense) until you understand the remaining code.

I think access to more powerful debugging features is essential for wider adoption and for managing larger configs or having non-cue-experts contribute to configs. I'd like to see more ideas for debugging tools and strategies discussed, but I'll focus on one particular idea in this "discussion".

cue explain command

I propose a cue explain command. Here's an example of how it would work:

Input:

things: [string]: {
  color: "red"
}

things: apple: {
    color: string
    name: color + " apple"
}

CUE eval output:

things: {
	apple: {
		color: "red"
		name:  "red apple"
	}
}

CUE explain usage:

cue explain things.apple.name config.cue

CUE explain output:

config.cue:2  color: "red"
config.cue:6    color: string
config.cue:7    name: color + " apple"

The idea is to find all the lines of CUE config that affect the rendering of a particular output value. This example is very basic and I'm not particularly attached to the naming or output format, but it shows one potential starting point. The syntax for selecting elements to "explain" could be refined, the output format could be refined. This is just a starting point for a discussion.

Potential problems

Text editor integration would be incredibly useful for something like this, but to do that, we need to go from the "eval" output back to the source. Unfortunately, there's way too much freedom in the different ways that we can output configs from CUE, so going backwards is difficult in practice. In practice we never really use a raw eval and take its output directly. We use cmd (_tool.cue files). The number of possible transformations that these files apply is not quite unlimited, but trying to go backwards from a file output is quite different from going backwards from an eval output. Let's say that we output configs with this tool.cue file:

command: write: task: write: file.Create & {
    filename: "thing.yaml"
    contents: yaml.Marshal(things.apple)
}

It would take quite a bit of reversing logic to figure out that name in the yaml file thing.yaml was produced by:

tool.cue:3    contents: yaml.Marshal(things.apple)
config.cue:2  color: "red"
config.cue:6    color: string
config.cue:7    name: color + " apple"

I don't know if this is possible or not. I think it's possible if every standard library function keeps track of its source data, but I don't know enough about how CUE is implement to know if this is realistic to implement.

For completeness of the thought exercise, I'll show one way in which the above query would be run with the hypothetical cue explain command:

cue explain --file thing.yaml name .

[cueckoo]

Original reply by @mpvl in cuelang/cue#927 (comment)

Yes, absolutely. Although indeed it is good to design a language such that one does not need debugging support too much, it is still a critical feature. Issue #142 is already an old issue, but it is nonetheless considered high priority, and @myitcv is currently working on this, in fact.

Linking evaluated code back to source is actually relatively easy, as CUE internally keeps track of all conjuncts, including line information, of which a result is composed. Position information is even kept across translations of foreign formats, like YAML (subject to the limits of the conversion libraries).

The hardest part really in providing something like cue explain is the naming and design of the UI/UX around it.
Note that it would also be useful to go the other way (where in my config is this field used) among other things. So one has to come up with good names to differentiate between all these modes. It probably makes sense to copy some of the naming from the spreadsheet world, where similar kind of analysis exists.

[cueckoo]

Original reply by @vikstrous2 in cuelang/cue#927 (comment)

You are right that going in both directions is useful.

In terms of UX, I can already imagine how it would look in the playground.

Forward:

Backward:

It's obviously harder to make this work in an IDE because any yaml file could have been derived from any CUE file.

Extra thought: If editors could have support for auto-running the cue config somehow, that could make for a really slick experience, similar to editing markdown with a live preview.

[cueckoo]

Original reply by @mpvl in cuelang/cue#927 (comment)

Extra thought: If editors could have support for auto-running the cue config somehow, that could make for a really slick experience, similar to editing markdown with a live preview.

Yes these are all the kind of features that one might expect from an LSP setup.