internal: separate the zero EvaluatorVersion value from EvalV2

We used to only have two valid EvaluatorVersion values via iota;
0 for EvalV2, also known as EvalDefault,
and 1 for EvalV3, also known as EvalExperiment.

The main issue with this approach is that it's impossible to tell
whether an evaluator version value was not initialised properly,
as its zero value already described EvalV2. Such a scenario could easily
lead to bugs, such as the user setting CUE_EXPERIMENT=evalv3
and the value not being propagated leading to using EvalV2 instead.

Separate the zero value as EvalVersionUnset, and stop using iota
so that it's clear that the values should be static over time.

Signed-off-by: Daniel Martí <[email protected]>
Change-Id: I2d3695d32d6ccfbd6afda31492aeba56e41fc79b
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1202744
Reviewed-by: Marcel van Lohuizen <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

cue/cuecontext/cuecontext.go

@@ -67,21 +67,21 @@ type EvalVersion = internal.EvaluatorVersion
 
 const (
 	// EvalDefault is the latest stable version of the evaluator.
-	EvalDefault EvalVersion = EvalV2
+	EvalDefault EvalVersion = internal.DefaultVersion
 
 	// EvalExperiment refers to the latest unstable version of the evaluator.
 	// Note that this version may change without notice.
-	EvalExperiment EvalVersion = EvalV3
+	EvalExperiment EvalVersion = internal.DevVersion
 
 	// EvalV2 is the currently latest stable version of the evaluator.
 	// It was introduced in CUE version 0.3 and is being maintained until 2024.
-	EvalV2 EvalVersion = internal.DefaultVersion
+	EvalV2 EvalVersion = internal.EvalV2
 
 	// EvalV3 is the currently experimental version of the evaluator.
 	// It was introduced in 2024 and brought a new disjunction algorithm,
 	// a new closedness algorithm, a new core scheduler, and adds performance
 	// enhancements like structure sharing.
-	EvalV3 EvalVersion = internal.DevVersion
+	EvalV3 EvalVersion = internal.EvalV3
 )
 
 // EvaluatorVersion indicates which version of the evaluator to use. Currently

internal/internal.go

@@ -107,14 +107,27 @@ func Version(minor, patch int) int {
 	return -1000 + 100*minor + patch
 }
 
+// EvaluatorVersion is declared here so it can be used everywhere without import cycles,
+// but the canonical documentation lives at [cuelang.org/go/cue/cuecontext.EvalVersion].
+//
+// TODO(mvdan): rename to EvalVersion for consistency with cuecontext.
 type EvaluatorVersion int
 
 const (
-	DefaultVersion EvaluatorVersion = iota
+	// EvalVersionUnset is the zero value, which signals that no evaluator version is provided.
+	EvalVersionUnset EvaluatorVersion = 0
+
+	// The values below are documented under [cuelang.org/go/cue/cuecontext.EvalVersion].
+	// We should never change or delete the values below, as they describe all known past versions
+	// which is useful for understanding old debug output.
+
+	EvalV2 EvaluatorVersion = 2
+	EvalV3 EvaluatorVersion = 3
+
+	// The current default and experimental versions.
 
-	// The DevVersion is used for new implementations of the evaluator that
-	// do not cover all features of the CUE language yet.
-	DevVersion
+	DefaultVersion = EvalV2 // TODO(mvdan): rename to EvalDefault for consistency with cuecontext
+	DevVersion     = EvalV3 // TODO(mvdan): rename to EvalExperiment for consistency with cuecontext
 )
 
 // ListEllipsis reports the list type and remaining elements of a list. If we