golang.org/x/mod v0.39.0: module.VersionError

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 golang.org/x/mod/module.VersionError in pkg:golang/golang.org/x/mod@v0.39.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/mod@v0.39.0
Demonstrate these symbols/APIs:
  - golang.org/x/mod/module.VersionError

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.

{"case":{"caseId":"case:sha256:4b16ad9da3da440cdf257923d0bf9d06e521d73a40ceafed3a611d46f6279e58","contract":["module.VersionError returns *ModuleError wrapping standard error with specified Path and Version","module.VersionError returns err unchanged when err is already *ModuleError with matching Path and Version","module.VersionError wraps existing *ModuleError when Path or Version differs","module.VersionError wraps *InvalidVersionError producing formatted message with invalid noun description","module.VersionError returns an error that unwraps to the original underlying error via errors.Is and errors.Unwrap"],"goal":"verify golang.org/x/mod/module.VersionError in pkg:golang/golang.org/x/mod@v0.39.0","kind":"HOW","packages":["pkg:golang/golang.org/x/mod@v0.39.0"],"schemaVersion":1,"symbols":["golang.org/x/mod/module.VersionError"]},"contractCommand":["go","run","./test"],"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/golang.org/x/mod@v0.39.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/mod@v0.39.0","symbols":["golang.org/x/mod/module.VersionError"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.25.0

require golang.org/x/mod v0.39.0

golang.org/x/mod v0.39.0 h1:UF5zwQdCRRUpHfyPwr7d4UrGiVeldIsogtzWVnczL74=
golang.org/x/mod v0.39.0/go.mod h1:bvIbwjQ0HUFFf5AKukeeYQG4ZBUG9yxQbR9aEweIwYY=

package main

import (
	"errors"
	"fmt"

	"golang.org/x/mod/module"
)

func main() {
	v := module.Version{Path: "example.com/mod", Version: "v1.0.0"}
	err := module.VersionError(v, errors.New("resolution failed"))
	if err != nil {
		var modErr *module.ModuleError
		if errors.As(err, &modErr) {
			fmt.Printf("Module error: %s@%s: %v\n", modErr.Path, modErr.Version, modErr.Err)
			fmt.Printf("Formatted message: %s\n", modErr.Error())
			return
		}
		fmt.Printf("Unexpected error: %v\n", err)
		return
	}
	fmt.Println("No version error.")
}

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/mod/module.VersionError in pkg:golang/golang.org/x/mod@v0.39.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/mod@v0.39.0"
  ],
  "symbols": [
    "golang.org/x/mod/module.VersionError"
  ]
}

package main

import (
	"errors"
	"fmt"
	"os"

	"golang.org/x/mod/module"
)

func main() {
	// 1. module.VersionError returns *ModuleError wrapping standard error with specified Path and Version
	{
		v := module.Version{Path: "example.com/foo", Version: "v1.2.3"}
		cause := errors.New("resolution failed")
		err := module.VersionError(v, cause)
		if err == nil {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected error from VersionError\n")
			os.Exit(1)
		}
		var me *module.ModuleError
		if !errors.As(err, &me) {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected *module.ModuleError, got %T\n", err)
			os.Exit(1)
		}
		if me.Path != "example.com/foo" {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected Path 'example.com/foo', got %q\n", me.Path)
			os.Exit(1)
		}
		if me.Version != "v1.2.3" {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected Version 'v1.2.3', got %q\n", me.Version)
			os.Exit(1)
		}
		if me.Err != cause {
			fmt.Fprintf(os.Stderr, "assertion 1 failed: expected wrapped Err to match cause\n")
			os.Exit(1)
		}
	}

	// 2. module.VersionError returns err unchanged when err is already *ModuleError with matching Path and Version
	{
		v := module.Version{Path: "example.com/foo", Version: "v1.2.3"}
		origErr := &module.ModuleError{
			Path:    "example.com/foo",
			Version: "v1.2.3",
			Err:     errors.New("inner error"),
		}
		err := module.VersionError(v, origErr)
		if err != origErr {
			fmt.Fprintf(os.Stderr, "assertion 2 failed: expected identical error pointer when Path and Version match\n")
			os.Exit(1)
		}
	}

	// 3. module.VersionError wraps existing *ModuleError when Path or Version differs
	{
		vNew := module.Version{Path: "example.com/bar", Version: "v2.0.0"}
		inner := &module.ModuleError{
			Path:    "example.com/foo",
			Version: "v1.0.0",
			Err:     errors.New("mismatch error"),
		}
		err := module.VersionError(vNew, inner)
		var me *module.ModuleError
		if !errors.As(err, &me) {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected *module.ModuleError\n")
			os.Exit(1)
		}
		if me == inner {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: expected wrapped error when Path/Version differs\n")
			os.Exit(1)
		}
		if me.Path != "example.com/bar" || me.Version != "v2.0.0" || me.Err != inner {
			fmt.Fprintf(os.Stderr, "assertion 3 failed: unexpected fields in wrapper: %+v\n", me)
			os.Exit(1)
		}
	}

	// 4. module.VersionError wraps *InvalidVersionError producing formatted message with invalid noun description
	{
		v := module.Version{Path: "example.com/pkg", Version: "v1.0"}
		ive := &module.InvalidVersionError{
			Version: "v1.0",
			Pseudo:  false,
			Err:     errors.New("not canonical"),
		}
		err := module.VersionError(v, ive)
		var me *module.ModuleError
		if !errors.As(err, &me) {
			fmt.Fprintf(os.Stderr, "assertion 4 failed: expected *module.ModuleError\n")
			os.Exit(1)
		}
		expectedMsg := "example.com/pkg@v1.0: invalid version: not canonical"
		if me.Error() != expectedMsg {
			fmt.Fprintf(os.Stderr, "assertion 4 failed: expected %q, got %q\n", expectedMsg, me.Error())
			os.Exit(1)
		}
	}

	// 5. module.VersionError returns an error that unwraps to the original underlying error via errors.Is and errors.Unwrap
	{
		root := errors.New("root failure")
		v := module.Version{Path: "example.com/baz", Version: "v1.0.0"}
		err := module.VersionError(v, root)
		if !errors.Is(err, root) {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: errors.Is did not match root cause\n")
			os.Exit(1)
		}
		if errors.Unwrap(err) != root {
			fmt.Fprintf(os.Stderr, "assertion 5 failed: errors.Unwrap did not return root cause\n")
			os.Exit(1)
		}
	}

	fmt.Println("All contract assertions passed.")
}