preguide: next steps for preguide schema

[myitcv]

At a high level we want to:

1. move to definition of #TerminalName to constrain _#stepCommon.Terminal
2. move to a more complete definitions of Steps: [name=string] that allows specialisation at language and/or scenario
3. move away from the negative constraint on

For 1 we should be able to do:

...

#StepTypeUploadFile:  #StepType & 4

#Guide: {

	#Step: (#Command | #CommandFile | #Upload | #UploadFile ) & {
		Name:     string
		StepType: #StepType
		Terminal: string
	}

	#stepCommon: {
		Name:     string
		StepType: #StepType
		Terminal: #TerminalName
	}

        ....

	#TerminalNames: [ for k, _ in Terminals {k}]
	#TerminalName: *#TerminalNames[0] | or(#TerminalNames)

	// Terminals defines the required remote VMs for a given guide
	Terminals: [name=string]: #Terminal & {
		Name: name
	}

But given we chose to have package instances themselves "implement" preguide.#Guide, then we need some way to be able to refer to the embedded definitions #Command etc (because they are effectively definitions on the instance of preguide.#Guide, given that they are defined in terms of regular fields of preguide.#Guide).

This approach by definition requires us to embed the preguide.#Guide definition in a script file. Which currently causes us to run into cuelang/cue#565.

For 2, we should be able to move to a definitions of Steps that looks something like this:

#Guide: {
	#Step: {
		// ...
	}

	#Scenario: {
		Name:  string
		Image: string
	}

	Scenarios: [not(_#Language)]: #Scenario & {
		Name: name
	}

	_#ScenarioName: or([ for name, _ in Scenarios {name}])

	Languages: [...#Language]
	_#Language: or(Languages)

	for scenario, _ in Scenarios for _, language in Languages {
		Steps: "\(scenario)": "\(language)": [string]: #Step
	}

	_#StepName: not(_#Language) & not(_#ScenarioName) & string

	// Now we know that _#Language, _#ScenarioName and _#StepName
	// are disjoint sets

	// Allow specification of steps at any level of granularity
	Steps: [name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [_#Language]: [name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [_#Language]: [_#ScenarioName]: [name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [_#ScenarioName]: [name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [_#ScenarioName]: [_#Language]: [name=_#StepName]: #Step & {
		Name: name
	}

	// Default finer granualrities from coarser ones

	Steps: [_#Language]: [name=string]:     *Steps[name] | #Step
	Steps: [_#ScenarioName]: [name=string]: *Steps[name] | #Step

	Steps: [lang=_#Language]: [_#ScenarioName]: [name=string]:     *Steps[lang][name] | #Step
	Steps: [scenario=_#ScenarioName]: [_#Language]: [name=string]: *Steps[scenario][name] | #Step

	// Constrain that the finest granularity of step should be consistent
	// regardless of how it is specified
	Steps: [scenario=_#ScenarioName]: [lang=_#Language]: [name=string]: Steps[lang][scenario][name]
}

#Language: "en" | "fr" // etc

This change is contingent on change 1, however. Because we need to drop our ok-based check on terminal names:

#ok: true & and([ for s in Steps for l in s {list.Contains(#TerminalNames, l.Terminal)}])

And it also requires us to have some answer on how we constrain _#ScenarioName to not be a language code. Two options on that front:

// Option 1
Scenarios: [#Language]: _|_

// Option 2
#ScenarioName: not(or(#Language))

This is covered in cuelang/cue#571.

The second change is also contingent on:

• the JSON Schema semantics of pattern fields being adopted
• resolution of cmd/cue: incomplete value from default cuelang/cue#577

With this second change we can effectively require that every step is well defined for every language in every scenario (via judicious use of defaults). That saves us ever having to implement that fallback logic in Go (although we could do if we don't get a solution to cuelang/cue#577). Under this proposal, languages are listed by the guide author; scenarios are declared along with the images they require. Therefore, we simply need to walks Steps to find all step names, at which point we have our universe to iterate.

One thing worth bearing in mind at this point is whether it is ever possible/required to only have a step defined for a specific scenario. If so, what does this mean?

[myitcv]

Note that cuelang/cue#565 and cuelang/cue#577 are now solved which unblocks much of this work.

[myitcv]

Note that in order to fully support the multi-format form of Steps, i.e. where any level of specialisation can be specified under the Steps field, we need cuelang/cue#785 at which point the definition would look something like this (partially shown):

#Guide: {
	Steps: [...name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [...#Language]: [...name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [...#Language]: [..._#ScenarioName]: [name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [..._#ScenarioName]: [...name=_#StepName]: #Step & {
		Name: name
	}
	Steps: [..._#ScenarioName]: [..._#Language]: [...name=_#StepName]: #Step & {
		Name: name
	}
}

cuelang/cue#571 shouldn't be a blocker here because we can define #Language and _#ScenarioName in such a way as to not clash with step names. Hence it will be unambiguous whether you are providing a simple step, or a language specialisation, or a language+scenario specialisation ... etc.

[myitcv]

In case cuelang/cue#571 is a block, we can work around this for now using explicit fields, and rewrite when additional field support lands:

#Guide: {
	Steps: [...name=_#StepName]: #Step & {
		Name: name
	}
	LanguageSteps: [...#Language]: [...name=_#StepName]: #Step & {
		Name: name
	}
	LanguageScenarioSteps: [...#Language]: [..._#ScenarioName]: [name=_#StepName]: #Step & {
		Name: name
	}
	ScenarioSteps: [..._#ScenarioName]: [...name=_#StepName]: #Step & {
		Name: name
	}
	ScenarioLanguageSteps: [..._#ScenarioName]: [..._#Language]: [...name=_#StepName]: #Step & {
		Name: name
	}
}

[myitcv]

A note to self/@marcosnils: when we come to add the full-blown Steps variant described in #115 (comment), we will need to add various constraints to ensure consistency. For example that a language-scenario specific step is the same as a scenario-language step when specified.