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

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.Wrap 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.Wrap

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:85ea214164824f5fadf851d69edd368e552300c6ec57bd40e44fc2cbbab0739c","contract":["Wrap returns nil when err is nil","Wrap prepends message to underlying error with colon and space separator","Wrap preserves underlying root error retrievable via errors.Cause","Wrap attaches stack trace retrievable via StackTrace method","Wrap supports Go 1.13 error chains via errors.Is","Wrap allows chaining multiple wrap annotations while preserving root cause","Wrap formats with empty message as colon and space prefix before underlying error"],"goal":"verify github.com/pkg/errors.Wrap 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.Wrap"]},"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.Wrap"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

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"
	"io"

	"github.com/pkg/errors"
)

// readResource simulates an operation that encounters an EOF error.
func readResource() error {
	return io.EOF
}

// processTask calls readResource and wraps the returned error with context.
func processTask() error {
	if err := readResource(); err != nil {
		return errors.Wrap(err, "failed to read resource")
	}
	return nil
}

func main() {
	// Demonstrating Wrap with nil error returns nil
	if err := errors.Wrap(nil, "no error"); err != nil {
		panic("expected nil error")
	}

	// Demonstrating Wrap annotating an error with context and stack trace
	err := processTask()
	if err != nil {
		fmt.Println("Formatted error:", err.Error())
		fmt.Println("Root cause:", errors.Cause(err))
	}
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/pkg/errors.Wrap 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.Wrap"
  ]
}

package main

import (
	stderrors "errors"
	"fmt"
	"os"

	pkgerrors "github.com/pkg/errors"
)

type stackTracer interface {
	StackTrace() pkgerrors.StackTrace
}

func main() {
	// 1. Wrap returns nil when err is nil
	if err := pkgerrors.Wrap(nil, "context on nil"); err != nil {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected nil, got %v\n", err)
		os.Exit(1)
	}

	rootErr := stderrors.New("disk full")

	// 2. Wrap prepends message to underlying error with colon and space separator
	wrapped := pkgerrors.Wrap(rootErr, "write failed")
	expectedMsg := "write failed: disk full"
	if wrapped.Error() != expectedMsg {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected %q, got %q\n", expectedMsg, wrapped.Error())
		os.Exit(1)
	}

	// 3. Wrap preserves underlying root error retrievable via errors.Cause
	if cause := pkgerrors.Cause(wrapped); cause != rootErr {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected root error %v, got %v\n", rootErr, cause)
		os.Exit(1)
	}

	// 4. Wrap attaches stack trace retrievable via StackTrace method
	tracer, ok := wrapped.(stackTracer)
	if !ok {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: expected wrapped error to implement stackTracer\n")
		os.Exit(1)
	}
	st := tracer.StackTrace()
	if len(st) == 0 {
		fmt.Fprintf(os.Stderr, "assertion 4 failed: expected non-empty stack trace\n")
		os.Exit(1)
	}

	// 5. Wrap supports Go 1.13 error chains via errors.Is
	if !stderrors.Is(wrapped, rootErr) {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: expected errors.Is(wrapped, rootErr) to be true\n")
		os.Exit(1)
	}

	// 6. Wrap allows chaining multiple wrap annotations while preserving root cause
	chained := pkgerrors.Wrap(wrapped, "request processing failed")
	expectedChainedMsg := "request processing failed: write failed: disk full"
	if chained.Error() != expectedChainedMsg {
		fmt.Fprintf(os.Stderr, "assertion 6 failed: expected %q, got %q\n", expectedChainedMsg, chained.Error())
		os.Exit(1)
	}
	if cause := pkgerrors.Cause(chained); cause != rootErr {
		fmt.Fprintf(os.Stderr, "assertion 6 failed: expected cause %v, got %v\n", rootErr, cause)
		os.Exit(1)
	}

	// 7. Wrap formats with empty message as colon and space prefix before underlying error
	emptyWrapped := pkgerrors.Wrap(rootErr, "")
	expectedEmptyMsg := ": disk full"
	if emptyWrapped.Error() != expectedEmptyMsg {
		fmt.Fprintf(os.Stderr, "assertion 7 failed: expected %q, got %q\n", expectedEmptyMsg, emptyWrapped.Error())
		os.Exit(1)
	}

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