go.yaml.in/yaml/v3 v3.0.5: yaml.Node

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify yaml.Node in pkg:golang/go.yaml.in/yaml/v3@v3.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.yaml.in/yaml/v3@v3.0.5
Demonstrate these symbols/APIs:
  - yaml.Node

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package sample

import (
	"bytes"
	"strings"
	"testing"

	"go.yaml.in/yaml/v3"
)

type ServiceDefinition struct {
	Name    string   `yaml:"name"`
	Port    int      `yaml:"port"`
	Tags    []string `yaml:"tags"`
	Enabled bool     `yaml:"enabled"`
}

func TestNodeASTStructure(t *testing.T) {
	raw := `
# Service specification
service:
  name: api-gateway
  ports:
    - 8080
    - 8443
  enabled: true
`
	var root yaml.Node
	if err := yaml.Unmarshal([]byte(raw), &root); err != nil {
		t.Fatalf("yaml.Unmarshal failed: %v", err)
	}

	if root.Kind != yaml.DocumentNode {
		t.Fatalf("expected DocumentNode, got kind %v", root.Kind)
	}
	if len(root.Content) != 1 {
		t.Fatalf("expected 1 document content node, got %d", len(root.Content))
	}

	docMapping := root.Content[0]
	if docMapping.Kind != yaml.MappingNode {
		t.Fatalf("expected MappingNode at document root, got kind %v", docMapping.Kind)
	}

	if len(docMapping.Content) != 2 {
		t.Fatalf("expected 2 nodes (1 key-value pair), got %d", len(docMapping.Content))
	}
	serviceKey := docMapping.Content[0]
	serviceVal := docMapping.Content[1]
	if serviceKey.Kind != yaml.ScalarNode || serviceKey.Value != "service" {
		t.Fatalf("expected scalar node 'service', got kind %v value %q", serviceKey.Kind, serviceKey.Value)
	}
	if serviceVal.Kind != yaml.MappingNode {
		t.Fatalf("expected MappingNode for service value, got kind %v", serviceVal.Kind)
	}

	if len(serviceVal.Content) != 6 {
		t.Fatalf("expected 6 nodes in service mapping, got %d", len(serviceVal.Content))
	}

	portsKey := serviceVal.Content[2]
	portsVal := serviceVal.Content[3]
	if portsKey.Value != "ports" {
		t.Fatalf("expected 'ports' key, got %q", portsKey.Value)
	}
	if portsVal.Kind != yaml.SequenceNode {
		t.Fatalf("expected SequenceNode for ports, got kind %v", portsVal.Kind)
	}
	if len(portsVal.Content) != 2 {
		t.Fatalf("expected 2 sequence items, got %d", len(portsVal.Content))
	}
	if portsVal.Content[0].Kind != yaml.ScalarNode || portsVal.Content[0].Value != "8080" {
		t.Fatalf("expected scalar '8080', got %q", portsVal.Content[0].Value)
	}
	if portsVal.Content[1].Kind != yaml.ScalarNode || portsVal.Content[1].Value != "8443" {
		t.Fatalf("expected scalar '8443', got %q", portsVal.Content[1].Value)
	}
}

func TestNodeCommentPreservation(t *testing.T) {
	raw := `
# Header description for service
app: auth-handler # Active authentication service
`
	var root yaml.Node
	if err := yaml.Unmarshal([]byte(raw), &root); err != nil {
		t.Fatalf("yaml.Unmarshal failed: %v", err)
	}

	if root.Kind != yaml.DocumentNode || len(root.Content) == 0 {
		t.Fatalf("expected document node with children")
	}

	mapping := root.Content[0]
	if len(mapping.Content) < 2 {
		t.Fatalf("expected key-value pair in mapping")
	}

	keyNode := mapping.Content[0]
	valNode := mapping.Content[1]

	if !strings.Contains(keyNode.HeadComment, "Header description for service") {
		t.Errorf("expected HeadComment to contain header text, got %q", keyNode.HeadComment)
	}
	if !strings.Contains(valNode.LineComment, "Active authentication service") {
		t.Errorf("expected LineComment to contain line text, got %q", valNode.LineComment)
	}
}

func TestNodeDecodeAndEncode(t *testing.T) {
	origin := ServiceDefinition{
		Name:    "worker-pool",
		Port:    9090,
		Tags:    []string{"internal", "batch"},
		Enabled: true,
	}

	var node yaml.Node
	if err := node.Encode(&origin); err != nil {
		t.Fatalf("node.Encode failed: %v", err)
	}

	if node.Kind != yaml.MappingNode {
		t.Fatalf("expected MappingNode from Encode, got kind %v", node.Kind)
	}

	var decoded ServiceDefinition
	if err := node.Decode(&decoded); err != nil {
		t.Fatalf("node.Decode failed: %v", err)
	}

	if decoded.Name != origin.Name || decoded.Port != origin.Port || decoded.Enabled != origin.Enabled {
		t.Fatalf("decoded struct mismatch: expected %+v, got %+v", origin, decoded)
	}
	if len(decoded.Tags) != len(origin.Tags) || decoded.Tags[0] != "internal" || decoded.Tags[1] != "batch" {
		t.Fatalf("decoded tags mismatch: %+v", decoded.Tags)
	}
}

func TestNodeASTModification(t *testing.T) {
	raw := `
# System configuration
host: localhost # primary host endpoint
timeout: 30
`
	var root yaml.Node
	if err := yaml.Unmarshal([]byte(raw), &root); err != nil {
		t.Fatalf("yaml.Unmarshal failed: %v", err)
	}

	mapping := root.Content[0]
	modified := false
	for i := 0; i < len(mapping.Content); i += 2 {
		if mapping.Content[i].Value == "host" {
			mapping.Content[i+1].Value = "internal.example.org"
			modified = true
			break
		}
	}
	if !modified {
		t.Fatal("failed to find 'host' key in AST")
	}

	var buf bytes.Buffer
	enc := yaml.NewEncoder(&buf)
	if err := enc.Encode(&root); err != nil {
		t.Fatalf("enc.Encode failed: %v", err)
	}
	if err := enc.Close(); err != nil {
		t.Fatalf("enc.Close failed: %v", err)
	}

	out := buf.String()
	if !strings.Contains(out, "internal.example.org") {
		t.Fatalf("expected modified host in serialized yaml, got:\n%s", out)
	}
	if !strings.Contains(out, "# System configuration") {
		t.Fatalf("expected header comment preserved in serialized yaml, got:\n%s", out)
	}
	if !strings.Contains(out, "# primary host endpoint") {
		t.Fatalf("expected line comment preserved in serialized yaml, got:\n%s", out)
	}
}

{"case":{"caseId":"case:sha256:dd06d6c5928c047960d6a0950e60f3a1be6a854e81a5acbae4c333d93393f67d","contract":["yaml.Node unmarshals YAML document hierarchy into DocumentNode, MappingNode, SequenceNode, and ScalarNode AST","yaml.Node preserves HeadComment and LineComment metadata on child AST nodes","yaml.Node Decode and Encode convert between structured Go data types and Node AST representations","yaml.Node enables programmatic AST scalar value modification and serialized comment preservation"],"goal":"verify yaml.Node in pkg:golang/go.yaml.in/yaml/v3@v3.0.5","kind":"HOW","packages":["pkg:golang/go.yaml.in/yaml/v3@v3.0.5"],"schemaVersion":1,"symbols":["yaml.Node"]},"contractCommand":["go","test","-v","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.yaml.in/yaml/v3@v3.0.5"],"schemaVersion":1,"subject":"pkg:golang/go.yaml.in/yaml/v3@v3.0.5","symbols":["yaml.Node"],"verifierAdapter":"golang@1"}

module sample

go 1.22

require go.yaml.in/yaml/v3 v3.0.5

go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=

{
  "schemaVersion": 1,
  "goal": "verify yaml.Node in pkg:golang/go.yaml.in/yaml/v3@v3.0.5",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.yaml.in/yaml/v3@v3.0.5"
  ],
  "symbols": [
    "yaml.Node"
  ]
}