golang.org/x/mod v0.40.0: compare, validate, and canonicalize semantic versions with semver

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: compare, validate, and canonicalize semantic versions with semver
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/mod@v0.40.0
Demonstrate these symbols/APIs:
  - semver.Build
  - semver.Canonical
  - semver.Compare
  - semver.IsValid
  - semver.Major
  - semver.MajorMinor
  - semver.Max
  - semver.Prerelease
  - semver.Sort

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:b8e36ca62118d5b01b5e0418ae1902f8c13c7d5c1e677f5a01694bab3d8e11d6","contract":["semver.IsValid reports true for valid semantic version strings and false for versions without v prefix or invalid format","semver.Compare compares two semantic version strings returning negative, zero, or positive integer","semver.Canonical returns the canonical form of a semantic version string stripping build metadata","semver.Major returns the major version prefix of a semantic version string","semver.MajorMinor returns the major and minor version prefix of a semantic version string","semver.Prerelease returns the prerelease extension part of a semantic version string","semver.Build returns the build metadata extension part of a semantic version string","semver.Max returns the maximum of two semantic version strings","semver.Sort sorts a slice of semantic version strings in ascending order according to semver precedence"],"goal":"compare, validate, and canonicalize semantic versions with semver","kind":"HOW","packages":["pkg:golang/golang.org/x/mod@v0.40.0"],"schemaVersion":1,"symbols":["semver.Build","semver.Canonical","semver.Compare","semver.IsValid","semver.Major","semver.MajorMinor","semver.Max","semver.Prerelease","semver.Sort"]},"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.40.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/mod@v0.40.0","symbols":["semver.Build","semver.Canonical","semver.Compare","semver.IsValid","semver.Major","semver.MajorMinor","semver.Max","semver.Prerelease","semver.Sort"],"verifierAdapter":"golang@1"}

module sample-golang-semver

go 1.25.0

require golang.org/x/mod v0.40.0

golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=

package main

import (
	"fmt"

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

func main() {
	v1 := "v1.2.3-beta.1+build100"
	v2 := "v1.2.3"

	fmt.Printf("IsValid(%q): %v\n", v1, semver.IsValid(v1))
	fmt.Printf("Canonical(%q): %s\n", v1, semver.Canonical(v1))
	fmt.Printf("Major(%q): %s\n", v1, semver.Major(v1))
	fmt.Printf("MajorMinor(%q): %s\n", v1, semver.MajorMinor(v1))
	fmt.Printf("Prerelease(%q): %s\n", v1, semver.Prerelease(v1))
	fmt.Printf("Build(%q): %s\n", v1, semver.Build(v1))
	fmt.Printf("Compare(%q, %q): %d\n", v1, v2, semver.Compare(v1, v2))
	fmt.Printf("Max(%q, %q): %s\n", v1, v2, semver.Max(v1, v2))

	versions := []string{"v2.0.0", "v1.0.4", "v1.2.0", "v1.0.0-alpha"}
	semver.Sort(versions)
	fmt.Printf("Sorted: %v\n", versions)
}

{
  "schemaVersion": 1,
  "goal": "compare, validate, and canonicalize semantic versions with semver",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/mod@v0.40.0"
  ],
  "symbols": [
    "semver.Build",
    "semver.Canonical",
    "semver.Compare",
    "semver.IsValid",
    "semver.Major",
    "semver.MajorMinor",
    "semver.Max",
    "semver.Prerelease",
    "semver.Sort"
  ]
}

package main

import (
	"fmt"
	"os"

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

func main() {
	// Assertion 1: semver.IsValid reports true for valid semantic version strings and false for versions without v prefix or invalid format
	{
		if !semver.IsValid("v1.2.3") {
			fmt.Fprintf(os.Stderr, "FAIL: semver.IsValid(v1.2.3) returned false\n")
			os.Exit(1)
		}
		if !semver.IsValid("v0.0.1-alpha.1+20200101") {
			fmt.Fprintf(os.Stderr, "FAIL: semver.IsValid(v0.0.1-alpha.1+20200101) returned false\n")
			os.Exit(1)
		}
		if semver.IsValid("1.2.3") {
			fmt.Fprintf(os.Stderr, "FAIL: semver.IsValid(1.2.3) returned true; expected false without 'v' prefix\n")
			os.Exit(1)
		}
		if semver.IsValid("v1.2.x") {
			fmt.Fprintf(os.Stderr, "FAIL: semver.IsValid(v1.2.x) returned true for invalid version\n")
			os.Exit(1)
		}
	}

	// Assertion 2: semver.Compare compares two semantic version strings returning negative, zero, or positive integer
	{
		if semver.Compare("v1.2.0", "v1.2.3") >= 0 {
			fmt.Fprintf(os.Stderr, "FAIL: expected semver.Compare(v1.2.0, v1.2.3) < 0\n")
			os.Exit(1)
		}
		if semver.Compare("v2.0.0", "v1.9.9") <= 0 {
			fmt.Fprintf(os.Stderr, "FAIL: expected semver.Compare(v2.0.0, v1.9.9) > 0\n")
			os.Exit(1)
		}
		if semver.Compare("v1.2.3", "v1.2.3") != 0 {
			fmt.Fprintf(os.Stderr, "FAIL: expected semver.Compare(v1.2.3, v1.2.3) == 0\n")
			os.Exit(1)
		}
		if semver.Compare("v1.0.0-alpha", "v1.0.0") >= 0 {
			fmt.Fprintf(os.Stderr, "FAIL: expected prerelease v1.0.0-alpha < release v1.0.0\n")
			os.Exit(1)
		}
	}

	// Assertion 3: semver.Canonical returns the canonical form of a semantic version string stripping build metadata
	{
		if canonical := semver.Canonical("v1.2.3-alpha.1+build123"); canonical != "v1.2.3-alpha.1" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Canonical did not strip build metadata: got %q, expected %q\n", canonical, "v1.2.3-alpha.1")
			os.Exit(1)
		}
		if canonical := semver.Canonical("v1.2.0"); canonical != "v1.2.0" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Canonical(v1.2.0) got %q, expected %q\n", canonical, "v1.2.0")
			os.Exit(1)
		}
		if canonical := semver.Canonical("invalid"); canonical != "" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Canonical(invalid) returned non-empty: %q\n", canonical)
			os.Exit(1)
		}
	}

	// Assertion 4: semver.Major returns the major version prefix of a semantic version string
	{
		if major := semver.Major("v2.3.4-beta"); major != "v2" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Major(v2.3.4-beta) got %q, expected %q\n", major, "v2")
			os.Exit(1)
		}
		if major := semver.Major("v0.1.2"); major != "v0" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Major(v0.1.2) got %q, expected %q\n", major, "v0")
			os.Exit(1)
		}
		if major := semver.Major("invalid"); major != "" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Major(invalid) got %q, expected empty string\n", major)
			os.Exit(1)
		}
	}

	// Assertion 5: semver.MajorMinor returns the major and minor version prefix of a semantic version string
	{
		if mm := semver.MajorMinor("v2.3.4-beta"); mm != "v2.3" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.MajorMinor(v2.3.4-beta) got %q, expected %q\n", mm, "v2.3")
			os.Exit(1)
		}
		if mm := semver.MajorMinor("v1.0.0"); mm != "v1.0" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.MajorMinor(v1.0.0) got %q, expected %q\n", mm, "v1.0")
			os.Exit(1)
		}
		if mm := semver.MajorMinor("invalid"); mm != "" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.MajorMinor(invalid) got %q, expected empty string\n", mm)
			os.Exit(1)
		}
	}

	// Assertion 6: semver.Prerelease returns the prerelease extension part of a semantic version string
	{
		if pre := semver.Prerelease("v1.2.3-rc.1+build"); pre != "-rc.1" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Prerelease(v1.2.3-rc.1+build) got %q, expected %q\n", pre, "-rc.1")
			os.Exit(1)
		}
		if pre := semver.Prerelease("v1.2.3"); pre != "" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Prerelease(v1.2.3) got %q, expected empty string\n", pre)
			os.Exit(1)
		}
	}

	// Assertion 7: semver.Build returns the build metadata extension part of a semantic version string
	{
		if bld := semver.Build("v1.2.3-rc.1+build99"); bld != "+build99" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Build(v1.2.3-rc.1+build99) got %q, expected %q\n", bld, "+build99")
			os.Exit(1)
		}
		if bld := semver.Build("v1.2.3"); bld != "" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Build(v1.2.3) got %q, expected empty string\n", bld)
			os.Exit(1)
		}
	}

	// Assertion 8: semver.Max returns the maximum of two semantic version strings
	{
		if max := semver.Max("v1.2.0", "v1.3.0"); max != "v1.3.0" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Max(v1.2.0, v1.3.0) got %q, expected %q\n", max, "v1.3.0")
			os.Exit(1)
		}
		if max := semver.Max("v2.1.0", "v2.0.5"); max != "v2.1.0" {
			fmt.Fprintf(os.Stderr, "FAIL: semver.Max(v2.1.0, v2.0.5) got %q, expected %q\n", max, "v2.1.0")
			os.Exit(1)
		}
	}

	// Assertion 9: semver.Sort sorts a slice of semantic version strings in ascending order according to semver precedence
	{
		versions := []string{"v1.3.0", "v1.1.0", "v2.0.0", "v1.0.0-beta", "v1.2.0"}
		semver.Sort(versions)
		expected := []string{"v1.0.0-beta", "v1.1.0", "v1.2.0", "v1.3.0", "v2.0.0"}
		for i, v := range versions {
			if v != expected[i] {
				fmt.Fprintf(os.Stderr, "FAIL: semver.Sort at index %d got %q, expected %q\n", i, v, expected[i])
				os.Exit(1)
			}
		}
	}

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