golang.org/x/mod v0.18.0: validate, escape, split, and match module paths and versions with module package

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: validate, escape, split, and match module paths and versions with module package
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/mod@v0.18.0
Demonstrate these symbols/APIs:
  - golang.org/x/mod/module.Check
  - golang.org/x/mod/module.CheckPath
  - golang.org/x/mod/module.EscapePath
  - golang.org/x/mod/module.EscapeVersion
  - golang.org/x/mod/module.MatchPathMajor
  - golang.org/x/mod/module.Sort
  - golang.org/x/mod/module.SplitPathVersion

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:f7818a7a1fa7a2cbc878fb9271f9c2996ce0748a11ffb5a6f508e351f65ec27f","contract":["module.CheckPath validates well-formed module paths and rejects invalid paths such as empty, leading or trailing slashes, and relative elements","module.Check validates module path and version pair requiring valid path and semantic version","module.EscapePath encodes uppercase letters into exclamation marks followed by lowercase for case-insensitive file systems","module.EscapeVersion encodes uppercase characters in version strings and rejects disallowed version strings","module.SplitPathVersion splits a module path into path prefix and major version suffix","module.MatchPathMajor reports whether a semantic version matches the path major suffix","module.Sort sorts a slice of module.Version in ascending order by Path then Version"],"goal":"validate, escape, split, and match module paths and versions with module package","kind":"HOW","packages":["pkg:golang/golang.org/x/mod@v0.18.0"],"schemaVersion":1,"symbols":["golang.org/x/mod/module.Check","golang.org/x/mod/module.CheckPath","golang.org/x/mod/module.EscapePath","golang.org/x/mod/module.EscapeVersion","golang.org/x/mod/module.MatchPathMajor","golang.org/x/mod/module.Sort","golang.org/x/mod/module.SplitPathVersion"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/golang.org/x/mod@v0.18.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/mod@v0.18.0","symbols":["golang.org/x/mod/module.Check","golang.org/x/mod/module.CheckPath","golang.org/x/mod/module.EscapePath","golang.org/x/mod/module.EscapeVersion","golang.org/x/mod/module.MatchPathMajor","golang.org/x/mod/module.Sort","golang.org/x/mod/module.SplitPathVersion"],"verifierAdapter":"golang@1"}

module sample-golang-module

go 1.25.0

require golang.org/x/mod v0.18.0

golang.org/x/mod v0.18.0 h1:5+9lSbEzPSdWkH32vYPBwEpX8KwDbM52Ud9xBUvNlb0=
golang.org/x/mod v0.18.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=

package main

import (
	"fmt"

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

func main() {
	// Validate module path
	path := "example.com/org/pkg/v2"
	if err := module.CheckPath(path); err != nil {
		fmt.Printf("CheckPath(%q) error: %v\n", path, err)
	} else {
		fmt.Printf("CheckPath(%q): valid\n", path)
	}

	// Validate module path and version pair
	if err := module.Check("example.com/mod", "v1.2.3"); err != nil {
		fmt.Printf("Check error: %v\n", err)
	} else {
		fmt.Printf("Check(example.com/mod, v1.2.3): valid\n")
	}

	// Escape path and version for case-insensitive file systems
	escPath, err := module.EscapePath("github.com/Azure/azure-sdk-for-go")
	if err == nil {
		fmt.Printf("EscapePath: %s\n", escPath)
	}

	escVer, err := module.EscapeVersion("v1.0.0-Beta.1")
	if err == nil {
		fmt.Printf("EscapeVersion: %s\n", escVer)
	}

	// Split module path and major version
	prefix, major, ok := module.SplitPathVersion("example.com/mod/v3")
	fmt.Printf("SplitPathVersion(%q): prefix=%q major=%q ok=%v\n", "example.com/mod/v3", prefix, major, ok)

	// Match semantic version with major path element
	matches := module.MatchPathMajor("v3.1.0", "/v3")
	fmt.Printf("MatchPathMajor(v3.1.0, /v3): %v\n", matches)

	// Sort slice of module.Version
	modules := []module.Version{
		{Path: "example.com/b", Version: "v1.0.0"},
		{Path: "example.com/a", Version: "v2.0.0"},
		{Path: "example.com/a", Version: "v1.0.0"},
	}
	module.Sort(modules)
	fmt.Printf("Sorted modules: %+v\n", modules)
}

{
  "schemaVersion": 1,
  "goal": "validate, escape, split, and match module paths and versions with module package",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/mod@v0.18.0"
  ],
  "symbols": [
    "golang.org/x/mod/module.Check",
    "golang.org/x/mod/module.CheckPath",
    "golang.org/x/mod/module.EscapePath",
    "golang.org/x/mod/module.EscapeVersion",
    "golang.org/x/mod/module.MatchPathMajor",
    "golang.org/x/mod/module.Sort",
    "golang.org/x/mod/module.SplitPathVersion"
  ]
}

package main

import (
	"fmt"
	"os"

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

func main() {
	// Assertion 1: module.CheckPath validates well-formed module paths and rejects invalid paths such as empty, leading or trailing slashes, and relative elements
	{
		validPaths := []string{
			"golang.org/x/mod",
			"github.com/example/repo",
			"example.com/pkg/v2",
		}
		for _, p := range validPaths {
			if err := module.CheckPath(p); err != nil {
				fmt.Fprintf(os.Stderr, "FAIL: module.CheckPath(%q) returned unexpected error: %v\n", p, err)
				os.Exit(1)
			}
		}

		invalidPaths := []string{
			"",
			"/leading/slash",
			"trailing/slash/",
			"double//slash",
			"path/./dot",
			"path/../dotdot",
		}
		for _, p := range invalidPaths {
			if err := module.CheckPath(p); err == nil {
				fmt.Fprintf(os.Stderr, "FAIL: module.CheckPath(%q) expected error but got nil\n", p)
				os.Exit(1)
			}
		}
	}

	// Assertion 2: module.Check validates module path and version pair requiring valid path and semantic version
	{
		if err := module.Check("example.com/mod", "v1.2.3"); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.Check(example.com/mod, v1.2.3) returned unexpected error: %v\n", err)
			os.Exit(1)
		}

		if err := module.Check("example.com/mod", "1.2.3"); err == nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.Check(example.com/mod, 1.2.3) expected error for version without 'v' prefix\n")
			os.Exit(1)
		}

		if err := module.Check("/invalid/path", "v1.0.0"); err == nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.Check(/invalid/path, v1.0.0) expected error for invalid path\n")
			os.Exit(1)
		}
	}

	// Assertion 3: module.EscapePath encodes uppercase letters into exclamation marks followed by lowercase for case-insensitive file systems
	{
		escaped, err := module.EscapePath("github.com/Azure/azure-sdk-for-go")
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapePath returned error: %v\n", err)
			os.Exit(1)
		}
		if expected := "github.com/!azure/azure-sdk-for-go"; escaped != expected {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapePath got %q, expected %q\n", escaped, expected)
			os.Exit(1)
		}

		escapedLower, err := module.EscapePath("example.com/alllower")
		if err != nil || escapedLower != "example.com/alllower" {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapePath on lowercase got %q (err: %v)\n", escapedLower, err)
			os.Exit(1)
		}

		if _, err := module.EscapePath("/invalid/path"); err == nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapePath expected error on invalid path\n")
			os.Exit(1)
		}
	}

	// Assertion 4: module.EscapeVersion encodes uppercase characters in version strings and rejects disallowed version strings
	{
		escaped, err := module.EscapeVersion("v1.0.0-Beta.1")
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapeVersion returned error: %v\n", err)
			os.Exit(1)
		}
		if expected := "v1.0.0-!beta.1"; escaped != expected {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapeVersion got %q, expected %q\n", escaped, expected)
			os.Exit(1)
		}

		if _, err := module.EscapeVersion("../invalid"); err == nil {
			fmt.Fprintf(os.Stderr, "FAIL: module.EscapeVersion expected error on disallowed version string\n")
			os.Exit(1)
		}
	}

	// Assertion 5: module.SplitPathVersion splits a module path into path prefix and major version suffix
	{
		prefix, major, ok := module.SplitPathVersion("example.com/mod/v2")
		if !ok || prefix != "example.com/mod" || major != "/v2" {
			fmt.Fprintf(os.Stderr, "FAIL: module.SplitPathVersion(example.com/mod/v2) got (%q, %q, %v)\n", prefix, major, ok)
			os.Exit(1)
		}

		prefix, major, ok = module.SplitPathVersion("example.com/mod")
		if !ok || prefix != "example.com/mod" || major != "" {
			fmt.Fprintf(os.Stderr, "FAIL: module.SplitPathVersion(example.com/mod) got (%q, %q, %v)\n", prefix, major, ok)
			os.Exit(1)
		}

		_, _, ok = module.SplitPathVersion("example.com/mod/v0")
		if ok {
			fmt.Fprintf(os.Stderr, "FAIL: module.SplitPathVersion(example.com/mod/v0) expected ok=false\n")
			os.Exit(1)
		}

		_, _, ok = module.SplitPathVersion("example.com/mod/v1")
		if ok {
			fmt.Fprintf(os.Stderr, "FAIL: module.SplitPathVersion(example.com/mod/v1) expected ok=false\n")
			os.Exit(1)
		}
	}

	// Assertion 6: module.MatchPathMajor reports whether a semantic version matches the path major suffix
	{
		if !module.MatchPathMajor("v2.3.4", "/v2") {
			fmt.Fprintf(os.Stderr, "FAIL: module.MatchPathMajor(v2.3.4, /v2) expected true\n")
			os.Exit(1)
		}
		if !module.MatchPathMajor("v1.2.3", "") {
			fmt.Fprintf(os.Stderr, "FAIL: module.MatchPathMajor(v1.2.3, \"\") expected true\n")
			os.Exit(1)
		}
		if !module.MatchPathMajor("v0.5.0", "") {
			fmt.Fprintf(os.Stderr, "FAIL: module.MatchPathMajor(v0.5.0, \"\") expected true\n")
			os.Exit(1)
		}
		if module.MatchPathMajor("v2.0.0", "") {
			fmt.Fprintf(os.Stderr, "FAIL: module.MatchPathMajor(v2.0.0, \"\") expected false\n")
			os.Exit(1)
		}
		if module.MatchPathMajor("v1.0.0", "/v2") {
			fmt.Fprintf(os.Stderr, "FAIL: module.MatchPathMajor(v1.0.0, /v2) expected false\n")
			os.Exit(1)
		}
	}

	// Assertion 7: module.Sort sorts a slice of module.Version in ascending order by Path then Version
	{
		list := []module.Version{
			{Path: "example.com/b", Version: "v1.0.0"},
			{Path: "example.com/a", Version: "v2.0.0"},
			{Path: "example.com/a", Version: "v1.0.0"},
			{Path: "example.com/a", Version: "v1.0.0-alpha"},
		}
		module.Sort(list)

		expected := []module.Version{
			{Path: "example.com/a", Version: "v1.0.0-alpha"},
			{Path: "example.com/a", Version: "v1.0.0"},
			{Path: "example.com/a", Version: "v2.0.0"},
			{Path: "example.com/b", Version: "v1.0.0"},
		}

		for i, v := range list {
			if v != expected[i] {
				fmt.Fprintf(os.Stderr, "FAIL: module.Sort at %d got %+v, expected %+v\n", i, v, expected[i])
				os.Exit(1)
			}
		}
	}

	fmt.Println("PASS: module contract passed")
}