validation,loader: add ValidateNode and NormalizeNode

ValidateNode is a native port of validation.Validate to *yaml.Node.
Each entry of the v2 checks map gets a Node twin in nodeChecks: file
mutual exclusion for configs / secrets, IP address validation for port
host_ip, count vs device_ids exclusivity for deploy.resources and gpus,
non-blank watch paths, and the external-with-extra-fields check for
volumes via checkVolumeNode / checkExternalNode. Tag and Kind are read
directly so callers no longer need to canonicalize before validating.

NormalizeNode is a bridge to the map-based Normalize: it decodes root,
runs Normalize, and rebuilds a yaml.Node from the result. This reuses
the well-tested rule set (default network injection, build context
defaults, implicit dependencies, env_file resolution, ...) without
porting 260 lines of orchestration in a single commit. Source positions
are lost on the rebuilt subtree; per-rule node-native ports will land
in subsequent commits and narrow the bridge until it can be removed.

Both functions tolerate a DocumentNode wrapper and nil root for
defensive use by the orchestrator.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

Author: ndeloof

loader/normalize_node.go

@@ -0,0 +1,69 @@
+/*
+   Copyright 2020 The Compose Specification 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
+
+       http://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 loader
+
+import (
+	"fmt"
+
+	"go.yaml.in/yaml/v4"
+
+	"github.com/compose-spec/compose-go/v3/types"
+)
+
+// NormalizeNode injects implicit defaults (default networks, derived service
+// dependencies, build defaults, ...) into a parsed yaml.Node tree using the
+// same rules as Normalize.
+//
+// First cut: the function bridges through map[string]any — it decodes root,
+// runs Normalize, and rebuilds a yaml.Node from the result. This reuses the
+// well-tested per-rule logic of the v2 implementation while keeping the v3
+// pipeline honest end-to-end. Subsequent commits will port the individual
+// normalization steps (networks, dependencies, builds, ...) to operate on
+// *yaml.Node directly so that source positions survive normalization for
+// downstream diagnostics; until then the rebuilt subtree has Line / Column
+// zero on synthesized nodes (default network, derived depends_on entries).
+//
+// NormalizeNode mutates root in place: the inner Content of the document
+// wrapper is replaced with the encoded normalized tree. Returns root for
+// convenience.
+func NormalizeNode(root *yaml.Node, env types.Mapping) (*yaml.Node, error) {
+	if root == nil {
+		return nil, nil
+	}
+	target := root
+	if target.Kind == yaml.DocumentNode && len(target.Content) == 1 {
+		target = target.Content[0]
+	}
+
+	var data map[string]any
+	if err := target.Decode(&data); err != nil {
+		return nil, fmt.Errorf("normalize: decode for bridge: %w", err)
+	}
+
+	normalized, err := Normalize(data, env)
+	if err != nil {
+		return nil, err
+	}
+
+	var rebuilt yaml.Node
+	if err := rebuilt.Encode(normalized); err != nil {
+		return nil, fmt.Errorf("normalize: re-encode after bridge: %w", err)
+	}
+
+	*target = rebuilt
+	return root, nil
+}

loader/normalize_node_test.go

@@ -0,0 +1,77 @@
+/*
+   Copyright 2020 The Compose Specification 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
+
+       http://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 loader
+
+import (
+	"testing"
+
+	"go.yaml.in/yaml/v4"
+	"gotest.tools/v3/assert"
+
+	"github.com/compose-spec/compose-go/v3/types"
+)
+
+func parseNormalizeNode(t *testing.T, src string) *yaml.Node {
+	t.Helper()
+	var doc yaml.Node
+	assert.NilError(t, yaml.Unmarshal([]byte(src), &doc))
+	return &doc
+}
+
+func decodeNormalize(t *testing.T, n *yaml.Node) map[string]any {
+	t.Helper()
+	var m map[string]any
+	assert.NilError(t, n.Decode(&m))
+	return m
+}
+
+func TestNormalizeNode_InjectsDefaultNetwork(t *testing.T) {
+	root := parseNormalizeNode(t, `
+name: app
+services:
+  web:
+    image: nginx
+`)
+	out, err := NormalizeNode(root, types.Mapping{})
+	assert.NilError(t, err)
+	m := decodeNormalize(t, out)
+	nets, ok := m["networks"].(map[string]any)
+	assert.Assert(t, ok, "default network injected: %v", m["networks"])
+	_, hasDefault := nets["default"]
+	assert.Assert(t, hasDefault, "networks.default should be created")
+}
+
+func TestNormalizeNode_BuildContextDefaultsToDot(t *testing.T) {
+	root := parseNormalizeNode(t, `
+name: app
+services:
+  web:
+    build:
+      dockerfile: Dockerfile
+`)
+	out, err := NormalizeNode(root, types.Mapping{})
+	assert.NilError(t, err)
+	m := decodeNormalize(t, out)
+	build := m["services"].(map[string]any)["web"].(map[string]any)["build"].(map[string]any)
+	assert.Equal(t, build["context"], ".")
+}
+
+func TestNormalizeNode_NilSafe(t *testing.T) {
+	out, err := NormalizeNode(nil, types.Mapping{})
+	assert.NilError(t, err)
+	assert.Assert(t, out == nil)
+}

validation/node.go

@@ -0,0 +1,154 @@
+/*
+   Copyright 2020 The Compose Specification 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
+
+       http://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 validation
+
+import (
+	"fmt"
+	"net"
+	"strings"
+
+	"go.yaml.in/yaml/v4"
+
+	"github.com/compose-spec/compose-go/v3/tree"
+)
+
+type nodeChecker func(n *yaml.Node, p tree.Path) error
+
+// nodeChecks mirrors `checks` but operates on *yaml.Node so the v3 pipeline
+// can validate the merged tree without round-tripping through map[string]any.
+// Entries stay in sync with the legacy map; the v2 map disappears when the
+// map-based code path is removed.
+var nodeChecks = map[tree.Path]nodeChecker{
+	"volumes.*":                       checkVolumeNode,
+	"configs.*":                       checkFileObjectNode("file", "environment", "content"),
+	"secrets.*":                       checkFileObjectNode("file", "environment"),
+	"services.*.ports.*":              checkIPAddressNode,
+	"services.*.develop.watch.*.path": checkPathNode,
+	"services.*.deploy.resources.reservations.devices.*": checkDeviceRequestNode,
+	"services.*.gpus.*": checkDeviceRequestNode,
+}
+
+// ValidateNode walks root and applies the per-path validation checks. The
+// tree is not mutated; only errors are reported. The function returns at the
+// first failing check, with the offending tree.Path included in the error so
+// callers can map it back to a source location.
+func ValidateNode(root *yaml.Node) error {
+	if root == nil {
+		return nil
+	}
+	target := root
+	if target.Kind == yaml.DocumentNode && len(target.Content) == 1 {
+		target = target.Content[0]
+	}
+	return checkNode(target, tree.NewPath())
+}
+
+func checkNode(n *yaml.Node, p tree.Path) error {
+	if n == nil {
+		return nil
+	}
+	for pattern, fn := range nodeChecks {
+		if p.Matches(pattern) {
+			return fn(n, p)
+		}
+	}
+	switch n.Kind {
+	case yaml.MappingNode:
+		for i := 0; i+1 < len(n.Content); i += 2 {
+			if err := checkNode(n.Content[i+1], p.Next(n.Content[i].Value)); err != nil {
+				return err
+			}
+		}
+	case yaml.SequenceNode:
+		for _, c := range n.Content {
+			if err := checkNode(c, p.Next(tree.PathMatchList)); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func checkFileObjectNode(keys ...string) nodeChecker {
+	return func(n *yaml.Node, p tree.Path) error {
+		if n == nil || n.Kind != yaml.MappingNode {
+			return nil
+		}
+		count := 0
+		for _, k := range keys {
+			if mappingFieldNode(n, k) != nil {
+				count++
+			}
+		}
+		if count > 1 {
+			return fmt.Errorf("%s: %s attributes are mutually exclusive", p, strings.Join(keys, "|"))
+		}
+		if count == 0 {
+			if mappingFieldNode(n, "driver") != nil {
+				// Custom driver: may carry its own content channel.
+				return nil
+			}
+			if mappingFieldNode(n, "external") == nil {
+				return fmt.Errorf("%s: one of %s must be set", p, strings.Join(keys, "|"))
+			}
+		}
+		return nil
+	}
+}
+
+func checkPathNode(n *yaml.Node, p tree.Path) error {
+	if n == nil || n.Kind != yaml.ScalarNode || n.Value == "" {
+		return fmt.Errorf("%s: value can't be blank", p)
+	}
+	return nil
+}
+
+func checkDeviceRequestNode(n *yaml.Node, p tree.Path) error {
+	if n == nil || n.Kind != yaml.MappingNode {
+		return nil
+	}
+	if mappingFieldNode(n, "count") != nil && mappingFieldNode(n, "device_ids") != nil {
+		return fmt.Errorf(`%s: "count" and "device_ids" attributes are exclusive`, p)
+	}
+	return nil
+}
+
+func checkIPAddressNode(n *yaml.Node, p tree.Path) error {
+	if n == nil || n.Kind != yaml.MappingNode {
+		return nil
+	}
+	ip := mappingFieldNode(n, "host_ip")
+	if ip == nil || ip.Kind != yaml.ScalarNode {
+		return nil
+	}
+	if net.ParseIP(ip.Value) == nil {
+		return fmt.Errorf("%s: invalid ip address: %s", p, ip.Value)
+	}
+	return nil
+}
+
+func mappingFieldNode(n *yaml.Node, key string) *yaml.Node {
+	if n == nil || n.Kind != yaml.MappingNode {
+		return nil
+	}
+	for i := 0; i+1 < len(n.Content); i += 2 {
+		if n.Content[i].Value == key {
+			return n.Content[i+1]
+		}
+	}
+	return nil
+}