internal/core/layer: rudimentary implementation of layers

This is not a language-level feature, but rather
something that can be controlled at the compilation
layer.

This supports:
- favoring one default over another
- treating data as defaults

It does not support:
- treating lists as scalars (it should)
- intuitive resolution of disjunctions

Signed-off-by: Marcel van Lohuizen <[e-mail]>
Change-Id: I1859fc9e253235b8f35645d1a834afd813cc5fba
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1224786
TryBot-Result: CUEcueckoo <[e-mail]>
Unity-Result: CUE porcuepine <[e-mail]>
Reviewed-by: Roger Peppe <[e-mail]>

cue/token/position.go

···
 	"sort"
 	"sync"
 
+	"cuelang.org/go/internal/core/layer"
 	"cuelang.org/go/internal/cueexperiment"
 )
 
···
 
 	x = *p.file.experiments
 	return x
+}
+
+// NOTE: this is an internal API and may change at any time without notice.
+func (p hiddenPos) Priority() (pr layer.Priority, ok bool) {
+	if f := p.file; f != nil {
+		return f.p, f.isData
+	}
+	return 0, false
 }
 
 // TODO(mvdan): The methods below don't need to build an entire Position
···
 	content []byte
 
 	experiments *cueexperiment.File
+	p           layer.Priority
+	isData      bool
 }
 
 // NewFile returns a new file with the given OS file name. The size provides the
···
 
 func (f *hiddenFile) SetExperiments(experiments *cueexperiment.File) {
 	f.experiments = experiments
+}
+
+// NOTE: this is an internal API and may change at any time without notice.
+//
+// SetLayer sets the layer priority for this file. The priority parameter
+// determines the precedence of defaults defined in this file, with higher
+// values taking precedence over lower values. The isData parameter indicates
+// whether this file should be treated as containing data defaults, which
+// have different merging semantics from regular defaults.
+func (f *hiddenFile) SetLayer(priority int8, isData bool) {
+	f.p = layer.Priority(priority)
+	f.isData = isData
 }
 
 // Name returns the file name of file f as registered with AddFile.

internal/core/adt/closed.go

···
 
 package adt
 
+import "cuelang.org/go/internal/core/layer"
+
 // This file implements the closedness algorithm.
 
 // Outline of algorithm
···
 
 	// This conjunct was opened by the ... postfix operator.
 	Opened bool
+
+	// Priority is used for default resolution. Higher values win. 0 means no
+	// priority is assigned. Default handling may be more restrictive than
+	// specified in the spec when a priority is assigned.
+	Priority layer.Priority
 
 	CycleInfo
 }

internal/core/adt/conjunct.go

···
 
 	case Value: // *NullLit, *BoolLit, *NumLit, *StringLit, *BytesLit, *Builtin
 		n.unshare()
+		if p, isData := pos(v).Priority(); isData {
+			id.Priority = p
+		}
+
 		n.updateCyclicStatusV3(id)
 
 		if y := n.scalar; y != nil {
+			p1 := n.scalarID.Priority
+			p2 := id.Priority
+			if p1 != 0 && p2 != 0 {
+				if p1 > p2 {
+					// all good
+					break
+				} else if p1 < p2 {
+					goto patchConjunct
+				}
+			}
 			if b, ok := BinOp(ctx, errOnDiffType, EqualOp, x, y).(*Bool); !ok || !b.B {
 				n.reportConflict(x, y, x.Kind(), y.Kind(), n.scalarID, id)
 			}
 			break
 		}
+	patchConjunct:
 		n.scalar = x
 		n.scalarID = id
+		// TODO: only set "scalarKnown" if there are no other high priority
+		// conjuncts. Alternatively, we should process high priority conjuncts
+		// in the scheduler first.
 		n.signal(scalarKnown)
 
 	default:

internal/core/adt/disjunct2.go

···
 
 package adt
 
-import "slices"
+import (
+	"math"
+	"slices"
+
+	"cuelang.org/go/internal/core/layer"
+)
 
 // # Overview
 //
···
 
 	leftDropsDefault := true
 	rightDropsDefault := true
+	priority, _ := pos(dn.src).Priority()
 
 	for i, p := range cross {
 		ID := n.nextCrossProduct(i, len(cross), p)
···
 				continue
 			}
 
+			// Promote the priority of defaults.
+			r.origPriority = priority
+			r.priority = p.origPriority
+			if p.defaultMode == isDefault && p.origPriority > priority {
+				r.origPriority = priority
+			}
+
 			tmp = append(tmp, r)
 			if p.defaultMode == isDefault || p.origDefaultMode == isDefault {
 				leftDropsDefault = false
···
 		// Unroll nested disjunctions.
 		switch len(r.disjuncts) {
 		case 0:
+			// If a default is not dropped in a higher priority, allow still to
+			// become a default, even if other other side has dropped defaults.
+			if !rightDropsDefault && r.origDefaultMode == notDefault &&
+				priority < r.priority {
+				r.origDefaultMode = maybeDefault
+			}
+			if !leftDropsDefault && r.defaultMode == notDefault &&
+				priority > r.priority {
+				r.defaultMode = maybeDefault
+			}
+
 			r.defaultMode = combineDefault2(r.defaultMode, r.origDefaultMode, leftDropsDefault, rightDropsDefault)
 			// r did not have a nested disjunction.
 			dst = appendDisjunct(n.ctx, dst, r)
···
 	// a special mode, or evaluating more aggressively if finalize is not given.
 	v.status = unprocessed
 
+	if m == isDefault {
+		c.CloseInfo.Priority, _ = pos(c.x).Priority()
+	}
 	d.scheduleConjunct(c, c.CloseInfo)
 
 	oc.unlinkOverlay()
···
 		return
 	}
 
+	// Determine highest priority and if the default exists.
+	hasDefaults := false
+	defaultPriority := layer.Priority(math.MinInt8)
+	for _, x := range n.disjuncts {
+		if x.defaultMode == isDefault {
+			hasDefaults = true
+			if x.origPriority > defaultPriority {
+				defaultPriority = x.origPriority
+			}
+		}
+	}
+
 	a := make([]Value, len(n.disjuncts))
 	p := 0
-	hasDefaults := false
 	for i, x := range n.disjuncts {
+		if x.origPriority < defaultPriority && x.defaultMode != isDefault {
+			x.defaultMode = notDefault
+		}
+
 		switch x.defaultMode {
 		case isDefault:
-			a[i] = a[p]
-			a[p] = x.node
-			p++
-			hasDefaults = true
-
+			if x.origPriority == defaultPriority {
+				a[i] = a[p]
+				a[p] = x.node
+				p++
+			}
 		case notDefault:
 			hasDefaults = true
 			fallthrough

internal/core/adt/eval.go

···
 	"cuelang.org/go/cue/errors"
 	"cuelang.org/go/cue/stats"
 	"cuelang.org/go/cue/token"
+	"cuelang.org/go/internal/core/layer"
 )
 
 // TODO TODO TODO TODO TODO TODO  TODO TODO TODO  TODO TODO TODO  TODO TODO TODO
···
 	shareDecremented bool       // counters of sharedIDs have been decremented
 
 	depth           int32
-	defaultMode     defaultMode // cumulative default mode
-	origDefaultMode defaultMode // default mode of the original disjunct
+	defaultMode     defaultMode    // cumulative default mode
+	origDefaultMode defaultMode    // default mode of the original disjunct
+	priority        layer.Priority // Priority corresponding to defaultMode
+	origPriority    layer.Priority // Priority of the original disjunct
 
 	// has a value filled out before the node splits into a disjunction. Aside
 	// from detecting a self-reference cycle when there is otherwise just an
···
 
 	// Value info
 
-	kind     Kind
-	kindExpr Expr      // expr that adjust last value (for error reporting)
-	kindID   CloseInfo // for error tracing
+	kind           Kind
+	constraintKind Kind
+	defaultKind    Kind
+	kindExpr       Expr      // expr that adjust last value (for error reporting)
+	kindID         CloseInfo // for error tracing
 
 	// Current value (may be under construction)
 	scalar   Value // TODO: use Value in node.
···
 			scheduler: n.scheduler,
 			node:      node,
 			nodeContextState: nodeContextState{
-				kind: TopKind,
+				kind:           TopKind,
+				constraintKind: TopKind,
+				defaultKind:    TopKind,
 			},
 			toFree:             n.toFree[:0],
 			arcMap:             n.arcMap[:0],
···
 			},
 			node: node,
 
-			nodeContextState: nodeContextState{kind: TopKind},
+			nodeContextState: nodeContextState{
+				kind:           TopKind,
+				constraintKind: TopKind,
+				defaultKind:    TopKind,
+			},
 		}
 	}
 

internal/core/adt/tasks.go

···
 
 	var ellipsis Node
 
-	id := t.id
+	id := c.subField(t.id)
 
 	index := int64(0)
 	hasComprehension := false

internal/core/adt/typocheck.go

···
 	// as, at this point, it seems to be only used for debugging. We may
 	// want to consider having a separate field for this, though.
 	ci.FromEmbed = false
+
+	// The priority should be cleared for sub fields: we take default struct
+	// in its entirety, but not piecemeal.
+	ci.Priority = 0
 	return ci
 }
 

internal/core/layer/layer.go

···
+// Copyright 2025 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package layer
+
+type Priority int8
+
+// TODO: algorithm for handling disjunctions more intuitively with layering.
+// For instance, how do we handle this case?:
+//
+// 		x: {} | *{
+// 		  b: x: 1
+// 		  c: x: 2
+// 		}
+// 		// 		If y > x, does the 2 of b force the default of x to fail? Could be an option.
+// 		y: {
+// 		  b: *{x: 2} | {}
+// 		  c: *{x: 3} | {}
+// 		}

internal/core/layer/layer_test.go

···
+// Copyright 2025 CUE Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package layer_test
+
+import (
+	"fmt"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+
+	"cuelang.org/go/cue/ast"
+	"cuelang.org/go/cue/cuecontext"
+	"cuelang.org/go/cue/errors"
+	"cuelang.org/go/internal/core/adt"
+	"cuelang.org/go/internal/cuedebug"
+	"cuelang.org/go/internal/cuetxtar"
+)
+
+func TestLayers(t *testing.T) {
+	adt.DebugDeps = true // check unmatched dependencies.
+
+	test := cuetxtar.TxTarTest{
+		Root: "./testdata",
+		Name: "layer",
+	}
+
+	cuedebug.Init()
+
+	test.Run(t, func(t *cuetxtar.Test) {
+		a := t.Instance()
+		ctx := cuecontext.New()
+
+		// Inject layering based on @layer attribute.
+		for _, f := range a.Files {
+			for i, d := range f.Decls {
+				_ = i
+				attr, ok := d.(*ast.Attribute)
+				if !ok {
+					// no preamble
+					break
+				}
+				key, body := attr.Split()
+				if key != "layer" {
+					continue
+				}
+
+				args := strings.Split(body, ",")
+
+				priority, err := strconv.ParseInt(args[0], 10, 8)
+				if err != nil {
+					t.Fatalf("invalid priority %q: %v", args[0], err)
+				}
+
+				f.Pos().File().SetLayer(
+					int8(priority),
+					slices.Contains(args, "defaultData"),
+				)
+
+				f.Decls = slices.Delete(f.Decls, i, i+1)
+				break
+			}
+		}
+
+		v := ctx.BuildInstance(a)
+		if err := v.Err(); err != nil {
+			t.WriteErrors(errors.Promote(err, "layers"))
+			return
+		}
+
+		s := fmt.Sprint(v)
+		t.Write([]byte(s))
+	})
+}

internal/core/layer/testdata/data.txtar

···
+-- a.cue --
+@layer(2,defaultData)
+x: {
+	b: { x: 1 }
+	c: { x: 2 }
+}
+-- b.cue --
+@layer(3,defaultData)
+x: c: { x: 3 }
+
+-- out/layer --
+{
+	x: {
+		b: {
+			x: 1
+		}
+		c: {
+			x: 3
+		}
+	}
+}

internal/core/layer/testdata/data_list.txtar

···
+-- a.cue --
+@layer(2,defaultData)
+list: [2]
+-- b.cue --
+@layer(3,defaultData)
+list: [3]
+-- out/layer --
+{
+	list: [2]
+}

internal/core/layer/testdata/data_mixed.txtar

···
+-- a.cue --
+@layer(2,defaultData)
+mixed: {
+	fromData: 1
+	fromBoth: 2
+}
+-- b.cue --
+@layer(3)
+mixed: {
+	fromNormal: 10
+	fromBoth: 20
+}
+-- out/layer --
+mixed.fromBoth: conflicting values 20 and 2:
+    ./a.cue:4:12
+    ./b.cue:4:12

internal/core/layer/testdata/data_nested_lists.txtar

···
+# TODO: treat lists as "scalars" in defaultsData mode
+-- a.cue --
+@layer(2,defaultData)
+nested: {
+	items: [1, 2]
+	config: {
+		values: ["a"]
+	}
+}
+-- b.cue --
+@layer(3,defaultData)
+nested: {
+	items: [3, 4, 5]
+	config: {
+		values: ["b", "c"]
+	}
+}
+-- out/layer --
+nested.items: incompatible list lengths (2 and 3):
+    ./b.cue:3:9

internal/core/layer/testdata/observe_costraints.txtar

···
+-- low.cue --
+@layer(3)
+
+a: int | *1
+b: _
+c: a & b
+-- high.cue --
+@layer(5)
+
+b: int | *"foo" // foo does not unify with int, so is eliminated
+-- out/layer --
+{
+	a: *1 | int
+	b: *"foo" | int
+	c: *1 | int
+}

internal/core/layer/testdata/scalar.txtar

···
+-- low.cue --
+@layer(3)
+
+a: int | *1
+
+-- high.cue --
+@layer(5)
+
+a: int | *2
+-- out/layer --
+{
+	a: *2 | 1 | int
+}

internal/core/layer/testdata/scalar_cross_layer.txtar

···
+-- low.cue --
+@layer(3)
+
+a1: int | *1
+b1: _
+c1: a1 & b1
+
+a2: _ | *1
+b2: _
+c2: a2 & b2
+
+-- high.cue --
+@layer(5)
+
+b1: int | *2
+
+b2: _ | *"foo"
+-- out/layer --
+{
+	a1: *1 | int
+	b1: *2 | int
+	c1: *2 | int | 1
+	a2: *1 | _
+	b2: *"foo" | _
+	c2: *"foo" | _ | 1
+}

internal/core/layer/testdata/scalar_multiple_defaults.txtar

···
+-- a.cue --
+@layer(2)
+
+x: string | *"low"
+y: int | *10
+-- b.cue --
+@layer(4)
+
+x: string | *"medium"
+z: bool | *true
+-- c.cue --
+@layer(6)
+
+x: string | *"high"
+y: int | *20
+z: bool
+-- out/layer --
+{
+	x: *"high" | string | "medium" | "low"
+	y: *20 | int | 10
+	z: *true | bool
+}

internal/core/layer/testdata/scalar_nested_defaults.txtar

···
+-- a.cue --
+@layer(3)
+
+config: {
+	port: int | *8080
+	host: string | *"localhost"
+}
+-- b.cue --
+@layer(5)
+
+config: {
+	port: int | *9000
+	timeout: int | *30
+}
+-- out/layer --
+{
+	config: {
+		port:    *9000 | int | 8080
+		host:    *"localhost" | string
+		timeout: *30 | int
+	}
+}