github.com/pkg/errors v0.9.1: WithMessagef

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 github.com/pkg/errors.WithMessagef in pkg:golang/github.com/pkg/errors@v0.9.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/pkg/errors@v0.9.1
Demonstrate these symbols/APIs:
  - github.com/pkg/errors.WithMessagef

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:5fa49c3a382d69b0f816f9a6dc2ab9fdfe95d7cfc2ab425a2fc1a3f9a412a295","contract":["WithMessagef returns nil when the input error is nil","WithMessagef annotates an existing error with a formatted string prefix","WithMessagef supports multiple format specifiers including strings and integers","WithMessagef preserves the underlying root cause accessible via errors.Cause","WithMessagef supports chaining multiple error context layers in sequential order"],"goal":"verify github.com/pkg/errors.WithMessagef in pkg:golang/github.com/pkg/errors@v0.9.1","kind":"HOW","packages":["pkg:golang/github.com/pkg/errors@v0.9.1"],"schemaVersion":1,"symbols":["github.com/pkg/errors.WithMessagef"]},"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/github.com/pkg/errors@v0.9.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/pkg/errors@v0.9.1","symbols":["github.com/pkg/errors.WithMessagef"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.25.0

require github.com/pkg/errors v0.9.1

github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

package main

import (
	"fmt"

	"github.com/pkg/errors"
)

// ProcessRecord simulates processing an item and annotates errors with formatted context.
func ProcessRecord(id int, action string) error {
	baseErr := errors.New("disk I/O timeout")
	return errors.WithMessagef(baseErr, "failed to %s record id %d", action, id)
}

func main() {
	err := ProcessRecord(101, "sync")
	if err != nil {
		fmt.Printf("Error occurred: %v\n", err)
		fmt.Printf("Root cause: %v\n", errors.Cause(err))
	}
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/pkg/errors.WithMessagef in pkg:golang/github.com/pkg/errors@v0.9.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/pkg/errors@v0.9.1"
  ],
  "symbols": [
    "github.com/pkg/errors.WithMessagef"
  ]
}

package main

import (
	"fmt"
	"os"

	"github.com/pkg/errors"
)

func main() {
	// 1. WithMessagef returns nil when the input error is nil
	if err := errors.WithMessagef(nil, "format %s", "test"); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: WithMessagef(nil) should return nil, got: %v\n", err)
		os.Exit(1)
	}

	// 2. WithMessagef annotates an existing error with a formatted string prefix
	baseErr := errors.New("connection refused")
	annotated := errors.WithMessagef(baseErr, "failed to connect to host %s port %d", "example.com", 8080)
	expectedMsg := "failed to connect to host example.com port 8080: connection refused"
	if annotated == nil || annotated.Error() != expectedMsg {
		fmt.Fprintf(os.Stderr, "FAIL: expected %q, got %v\n", expectedMsg, annotated)
		os.Exit(1)
	}

	// 3. WithMessagef supports multiple format specifiers including strings and integers
	var numRecords = 42
	var tableName = "users"
	formatted := errors.WithMessagef(baseErr, "batch insert into %s failed after %d attempts", tableName, numRecords)
	expectedFormatted := "batch insert into users failed after 42 attempts: connection refused"
	if formatted.Error() != expectedFormatted {
		fmt.Fprintf(os.Stderr, "FAIL: expected %q, got %q\n", expectedFormatted, formatted.Error())
		os.Exit(1)
	}

	// 4. WithMessagef preserves the underlying root cause accessible via errors.Cause
	rootCause := errors.Cause(annotated)
	if rootCause != baseErr {
		fmt.Fprintf(os.Stderr, "FAIL: expected root cause to match baseErr, got: %v\n", rootCause)
		os.Exit(1)
	}

	// 5. WithMessagef supports chaining multiple error context layers in sequential order
	outer := errors.WithMessagef(annotated, "handler %s aborted", "healthCheck")
	expectedOuter := "handler healthCheck aborted: failed to connect to host example.com port 8080: connection refused"
	if outer.Error() != expectedOuter {
		fmt.Fprintf(os.Stderr, "FAIL: expected chained error %q, got %q\n", expectedOuter, outer.Error())
		os.Exit(1)
	}
	if errors.Cause(outer) != baseErr {
		fmt.Fprintf(os.Stderr, "FAIL: expected root cause of chained error to match baseErr, got: %v\n", errors.Cause(outer))
		os.Exit(1)
	}

	fmt.Println("PASS: all contract assertions passed")
}