test(parity): run the ts-oracle in the pinned node image

The goldens recorded what the host's Node.js answered, so the same
reference functions gave other answers on another machine (URL parsing,
IDNA and Node.js error messages change between releases). The oracle
now bundles and runs in node:24-bookworm-slim, pinned by digest in
versions.yaml and handed in by the Taskfile, with no network: Node.js 24
is what CI installs and runs the reference on, and the newest release
the reference's lockfile builds on (its nan 2.25.0 does not compile
node-pty against Node.js 26). A bump that changes an answer fails the
oracle gate until the goldens are refreshed. The readLockfile oracle
writes its temporary folder as <dir>, so a message naming the file
stays the same from run to run. TestTSOracleGoldensMatchTheReference
skips without Docker or without TS_ORACLE_IMAGE, which task
parity:contract sets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: aledbf

Taskfile.yml

@@ -249,16 +249,16 @@ tasks:
       - 'echo "Schema refreshed. Run ''task spec:compliance'' — any new spec property fails until modeled in internal/config/types.go."'
 
   testdata:ts-oracle:
-    desc: Rewrite every internal/**/testdata/ts-oracle/*.json with the results of the reference TypeScript functions (tools/tsoracle)
+    desc: Rewrite every internal/**/testdata/ts-oracle/*.json with the results of the reference TypeScript functions (tools/tsoracle), run in the node image versions.yaml pins (needs Docker)
     deps: [reference:compile]
     cmds:
-      - go run ./cmd/devtool ts-oracle
+      - go run ./cmd/devtool ts-oracle "$(go tool versions ref node)"
 
   testdata:ts-oracle:check:
     desc: Fail when a testdata/ts-oracle golden differs from what the reference TypeScript functions return
     deps: [reference:compile]
     cmds:
-      - go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1 -v
+      - TS_ORACLE_IMAGE="$(go tool versions ref node)" go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1 -v
 
   reference:
     desc: Install and compile the TypeScript parity oracle
@@ -280,7 +280,7 @@ tasks:
       # must be in the inventory (needs reference/ checked out, so it lives here).
       - go test ./internal/cli -run TestOracleFlagCoverage -count=1
       # The ts-oracle goldens must be what the reference's functions return.
-      - go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1
+      - TS_ORACLE_IMAGE="$(go tool versions ref node)" go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1
       - PARITY_REPORT_FILE={{.ROOT_DIR}}/artifacts/parity-contract.json PARITY_STRICT=true PARITY_LANE=contract PARITY_SKIP_DOCKER=true PARITY_SKIP_NETWORK=true go test ./internal/cli -run TestParityMatrix -count=1 -timeout 10m -v {{.CLI_ARGS}}
 
   parity:semantic:

internal/devtools/command.go

@@ -49,7 +49,11 @@ func Main(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	case "metrics":
 		err = t.metrics(rest)
 	case "ts-oracle":
-		err = t.tsOracle(".", false)
+		if len(rest) != 1 {
+			fmt.Fprintln(stderr, "usage: devtool ts-oracle <node image>")
+			return 2
+		}
+		err = t.tsOracle(".", rest[0], false)
 	default:
 		fmt.Fprintf(stderr, "devtool: unknown command %q\n", cmd)
 		return 2
@@ -553,26 +557,49 @@ func (t tool) metrics(args []string) error {
 
 // tsOracle rewrites every internal/**/testdata/ts-oracle/*.json under root
 // with the answers the reference's own functions give to the golden's
-// requests; with check it writes nothing and fails on a stale golden.
+// requests; with check it writes nothing and fails on a stale golden. Node.js
+// runs in image, the node image versions.yaml pins (the Taskfile hands it in),
+// so the answers do not depend on the host's Node.js: URL parsing, IDNA and
+// JSON.parse messages change between releases.
 //
 // mutate-lane: TestTSOracleGoldensMatchTheReference
-func (t tool) tsOracle(root string, check bool) error {
+func (t tool) tsOracle(root, image string, check bool) error {
+	root, err := filepath.Abs(root)
+	if err != nil {
+		return err
+	}
+	// The reference may be a symlink out of the repository; esbuild reads it
+	// through its real path, so that path is mounted too.
+	reference, err := filepath.EvalSymlinks(filepath.Join(root, "reference"))
+	if err != nil {
+		return err
+	}
 	dir, err := os.MkdirTemp("", "ts-oracle-")
 	if err != nil {
 		return err
 	}
 	defer os.RemoveAll(dir)
+	node := func(mounts []string, args ...string) *exec.Cmd {
+		run := []string{"run", "--rm", "-i", "--network=none", "-u", fmt.Sprintf("%d:%d", os.Getuid(), os.Getgid())}
+		for _, m := range mounts {
+			run = append(run, "-v", m)
+		}
+		return exec.Command("docker", append(append(run, image, "node"), args...)...)
+	}
 	bundle := filepath.Join(dir, "oracle.js")
-	if err := t.run("node", filepath.Join(root, "tools/tsoracle/build.mjs"), filepath.Join(root, "reference"), bundle); err != nil {
-		return fmt.Errorf("bundle tools/tsoracle/oracle.ts: %w", err)
+	build := node([]string{root + ":" + root + ":ro", reference + ":" + reference + ":ro", dir + ":" + dir},
+		filepath.Join(root, "tools/tsoracle/build.mjs"), reference, bundle)
+	build.Stdout, build.Stderr = t.out, t.errw
+	if err := build.Run(); err != nil {
+		return fmt.Errorf("bundle tools/tsoracle/oracle.ts in %s: %w", image, err)
 	}
 	return refreshTSOracleFiles(root, func(request []byte) ([]byte, error) {
-		cmd := exec.Command("node", bundle)
+		cmd := node([]string{dir + ":" + dir + ":ro"}, bundle)
 		cmd.Stdin = bytes.NewReader(request)
 		cmd.Stderr = t.errw
 		out, err := cmd.Output()
 		if err != nil {
-			return nil, fmt.Errorf("run the oracle: %w", err)
+			return nil, fmt.Errorf("run the oracle in %s: %w", image, err)
 		}
 		return out, nil
 	}, check, t.errw)

internal/devtools/command_test.go

@@ -121,6 +121,16 @@ func TestMainUsageErrors(t *testing.T) {
 	if code != 1 || out != "" || errOut != "devtool coverage-report: usage: coverage-report <profile|covdata-dir> [title]\n" {
 		t.Errorf("a command's error: code=%d stdout=%q stderr=%q", code, out, errOut)
 	}
+	// ts-oracle takes the node image, the one argument the Taskfile hands in.
+	for _, args := range [][]string{{"ts-oracle"}, {"ts-oracle", "a", "b"}} {
+		if code, out, errOut := runMain(t, "", args...); code != 2 || out != "" || errOut != "usage: devtool ts-oracle <node image>\n" {
+			t.Errorf("%q: code=%d stdout=%q stderr=%q", args, code, out, errOut)
+		}
+	}
+	// With its image it runs, and here, with no reference/ to bundle, fails.
+	if code, _, errOut := runMain(t, "", "ts-oracle", "node:test"); code != 1 || !strings.Contains(errOut, "reference") {
+		t.Errorf("ts-oracle with an image: code=%d stderr=%q, want the missing reference/", code, errOut)
+	}
 }
 
 func TestParityAffectedReadsFilesFromStdin(t *testing.T) {

internal/devtools/tsoracle_test.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"errors"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"slices"
 	"strings"
@@ -217,16 +218,24 @@ func TestRefreshTSOracleFiles(t *testing.T) {
 	}
 }
 
-// The recorded goldens are what the reference's functions return today. It
-// runs where `task reference` has installed the reference (the parity CI job,
-// through task parity:contract).
+// The recorded goldens are what the reference's functions return today, run in
+// the node image versions.yaml pins, which task parity:contract hands in as
+// TS_ORACLE_IMAGE. It runs where `task reference` has installed the reference
+// and Docker is reachable (the parity CI job).
 func TestTSOracleGoldensMatchTheReference(t *testing.T) {
 	const root = "../.."
+	image := os.Getenv("TS_ORACLE_IMAGE")
+	if image == "" {
+		t.Skip("TS_ORACLE_IMAGE not set; run it through task parity:contract or task testdata:ts-oracle:check")
+	}
 	if _, err := os.Stat(filepath.Join(root, "reference/node_modules/esbuild")); err != nil {
 		t.Skipf("reference not installed (%v); run `task reference`", err)
 	}
+	if err := exec.Command("docker", "info").Run(); err != nil {
+		t.Skipf("docker not reachable (%v); the oracle runs in the pinned node image", err)
+	}
 	var out strings.Builder
-	if err := (tool{out: &out, errw: &out}).tsOracle(root, true); err != nil {
+	if err := (tool{out: &out, errw: &out}).tsOracle(root, image, true); err != nil {
 		t.Fatalf("%v\n%s", err, out.String())
 	}
 }

internal/features/lockfile_oracle_test.go

@@ -3,8 +3,10 @@ package features
 import (
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/devcontainers/cli/internal/tsoracle/oracletest"
@@ -44,7 +46,8 @@ func TestTSOracleReadLockfile(t *testing.T) {
 			lockfile, initLockfile, err := ReadLockfile(filepath.Join(dir, "devcontainer.json"))
 			switch {
 			case err != nil:
-				return nil, err
+				// The oracle writes its temporary folder as <dir>.
+				return nil, errors.New(strings.ReplaceAll(err.Error(), dir, "<dir>"))
 			case initLockfile:
 				return "init", nil
 			case lockfile != nil:

tools/tsoracle/oracle.ts

@@ -117,6 +117,13 @@ const fns: Record<string, (...args: any[]) => any> = {
 			}
 			const { lockfile, initLockfile } = await readLockfile({ configFilePath: URI.file(path.join(dir, 'devcontainer.json')) } as any);
 			return initLockfile ? 'init' : lockfile ? 'lockfile' : 'none';
+		} catch (err: any) {
+			// The temporary folder is <dir> in the golden, so a message that names
+			// the file stays the same from run to run.
+			if (typeof err?.message === 'string') {
+				err.message = err.message.split(dir).join('<dir>');
+			}
+			throw err;
 		} finally {
 			fs.rmSync(dir, { recursive: true, force: true });
 		}

versions.yaml

@@ -13,6 +13,18 @@
     task lint, with this repository's .golangci.yml. go-tools' version, so the spin-stack
     repositories are measured by the same linter; the image's Go must be at least go.mod's.
 
+- name: node
+  kind: image
+  source: node
+  version: 24-bookworm-slim
+  pin: sha256:55fb5f5a527ea2c5c4a95f963e48ef90aa38c7b346054fdc8ee9957a2b55d205
+  track: digest
+  note: >-
+    The Node.js the ts-oracle runs the reference's functions in (task testdata:ts-oracle,
+    TestTSOracleGoldensMatchTheReference), so a golden does not depend on the host's Node: URL
+    parsing, IDNA and JSON.parse messages change between Node releases. A bump that changes an
+    answer fails the oracle gate until the goldens are refreshed and the Go ports follow.
+
 - name: distroless
   kind: image
   source: gcr.io/distroless/static