golang.org/x/mod v0.36.0: module.Check, semver.Compare, semver.Canonical

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

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/mod@v0.36.0

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:b82dfb9717f5cc7598b0650d694162814b7cbed5a50d3990b8e0a710d6dee246","contract":["module.Check validates standard v1 module paths and semantic versions","module.Check validates major version \u003e= 2 when module path ends with matching /vN suffix","module.Check returns *module.InvalidVersionError when major version \u003e= 2 lacks matching /vN path suffix","semver.Compare orders pre-release versions before release versions and ignores build metadata","semver.Canonical normalizes short semantic versions to vMAJOR.MINOR.PATCH and strips build metadata","modfile.Parse parses go.mod syntax and AddRequire with Format produces updated go.mod bytes"],"goal":"verify pkg:golang/golang.org/x/mod@v0.36.0","kind":"HOW","packages":["pkg:golang/golang.org/x/mod@v0.36.0"],"schemaVersion":1,"symbols":["module.Check","semver.Compare","semver.Canonical","modfile.Parse"]},"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.36.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/mod@v0.36.0","symbols":["module.Check","semver.Compare","semver.Canonical","modfile.Parse"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.25.0

require golang.org/x/mod v0.36.0

golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=

package main

import (
	"fmt"
	"log"

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

func main() {
	modPath := "example.com/service/v2"
	modVer := "v2.1.0"
	if err := module.Check(modPath, modVer); err != nil {
		log.Fatalf("module.Check(%s, %s) failed: %v", modPath, modVer, err)
	}
	fmt.Printf("Checked %s@%s (canonical %s)\n", modPath, modVer, semver.Canonical(modVer))

	content := []byte("module example.com/service/v2\n\ngo 1.24\n\nrequire example.com/core v1.0.0\n")
	parsed, err := modfile.Parse("go.mod", content, nil)
	if err != nil {
		log.Fatalf("modfile.Parse failed: %v", err)
	}
	fmt.Printf("Module %s requires %d dependency\n", parsed.Module.Mod.Path, len(parsed.Require))
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/golang.org/x/mod@v0.36.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/mod@v0.36.0"
  ]
}

package main

import (
	"errors"
	"fmt"
	"os"
	"strings"

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

func fail(format string, args ...any) {
	fmt.Fprintf(os.Stderr, format+"\n", args...)
	os.Exit(1)
}

func main() {
	// 1. module.Check validates standard v1 module paths and versions
	if err := module.Check("example.com/lib", "v1.4.2"); err != nil {
		fail("expected nil for valid v1 module, got: %v", err)
	}

	// 2. module.Check validates major version >= 2 with matching /vN suffix
	if err := module.Check("example.com/lib/v2", "v2.0.1"); err != nil {
		fail("expected nil for valid v2 module path, got: %v", err)
	}

	// 3. module.Check returns *module.InvalidVersionError when v2+ lacks /vN suffix
	errMismatch := module.Check("example.com/lib", "v2.0.1")
	var invVer *module.InvalidVersionError
	if !errors.As(errMismatch, &invVer) {
		fail("expected InvalidVersionError for missing /v2 suffix, got %T: %v", errMismatch, errMismatch)
	}

	// 4. semver.Compare orders pre-release and release versions and ignores build metadata
	if got := semver.Compare("v1.3.0-rc.1", "v1.3.0"); got != -1 {
		fail("semver.Compare(v1.3.0-rc.1, v1.3.0) = %d, want -1", got)
	}
	if got := semver.Compare("v1.3.0+meta1", "v1.3.0+meta2"); got != 0 {
		fail("semver.Compare(v1.3.0+meta1, v1.3.0+meta2) = %d, want 0", got)
	}

	// 5. semver.Canonical normalizes partial versions and removes build metadata
	if got := semver.Canonical("v1.5"); got != "v1.5.0" {
		fail("semver.Canonical(v1.5) = %q, want v1.5.0", got)
	}
	if got := semver.Canonical("v1.5.0+build9"); got != "v1.5.0" {
		fail("semver.Canonical(v1.5.0+build9) = %q, want v1.5.0", got)
	}

	// 6. modfile.Parse parses go.mod bytes and AddRequire updates requirements
	src := []byte("module example.com/demo\n\ngo 1.24\n\nrequire example.com/dep v1.0.0\n")
	mf, err := modfile.Parse("go.mod", src, nil)
	if err != nil {
		fail("modfile.Parse failed: %v", err)
	}
	if mf.Module == nil || mf.Module.Mod.Path != "example.com/demo" {
		fail("unexpected module path: %+v", mf.Module)
	}
	if err := mf.AddRequire("example.com/dep", "v1.2.0"); err != nil {
		fail("AddRequire failed: %v", err)
	}
	out, err := mf.Format()
	if err != nil || !strings.Contains(string(out), "example.com/dep v1.2.0") {
		fail("Format output missing updated requirement: %s (err=%v)", string(out), err)
	}

	fmt.Println("ok")
}