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

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.Wrapf 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.Wrapf
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:b62a99132fce89814100779cfcb08196d413ad50d022479c084157eae1e5e2e8","contract":["Wrapf returns nil when the underlying error is nil","Wrapf formats message and prepends it to underlying error separated by colon and space","Wrapf preserves underlying root error retrievable via errors.Cause","Wrapf supports Go 1.13 error unwrapping via errors.Unwrap and errors.Is","Wrapf captures call site stack trace accessible via StackTrace() method","Wrapf formats with %s and %v as colon-separated message, and %+v with multiline cause, message, and call site stack trace","Wrapf supports nested chaining while preserving the original root cause"],"goal":"verify github.com/pkg/errors.Wrapf 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.Wrapf"]},"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.Wrapf"],"verifierAdapter":"golang@1"}

module 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"
)

// stackTracer is an interface implemented by errors that provide stack traces.
type stackTracer interface {
	StackTrace() errors.StackTrace
}

// simulateFetch simulates a network operation that fails.
func simulateFetch(id int) error {
	return errors.Wrapf(io.ErrUnexpectedEOF, "failed to fetch record %d", id)
}

func main() {
	// Demonstrating Wrapf with nil error
	if err := errors.Wrapf(nil, "no-op on nil id %d", 0); err != nil {
		panic("expected nil error")
	}

	// Demonstrating Wrapf annotating an error with format specifiers
	err := simulateFetch(42)
	if err != nil {
		fmt.Println("Formatted error:", err.Error())
		fmt.Println("Root cause:", errors.Cause(err))
		if tracer, ok := err.(stackTracer); ok {
			st := tracer.StackTrace()
			if len(st) > 0 {
				fmt.Printf("Top stack frame: %v\n", st[0])
			}
		}
	}
}

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

package main

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

	"github.com/pkg/errors"
)

type stackTracer interface {
	StackTrace() errors.StackTrace
}

func main() {
	if err := runContract(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract verification failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All github.com/pkg/errors.Wrapf contract assertions passed successfully.")
}

func runContract() error {
	// 1. Wrapf returns nil when the underlying error is nil
	if err := errors.Wrapf(nil, "formatted %s with code %d", "message", 100); err != nil {
		return fmt.Errorf("expected Wrapf(nil, ...) to return nil, got %v", err)
	}

	// 2. Wrapf formats message and prepends it to underlying error separated by colon and space
	rootErr := fmt.Errorf("connection refused")
	wrapped := errors.Wrapf(rootErr, "query failed for user %s on port %d", "alice", 5432)
	expectedMsg := "query failed for user alice on port 5432: connection refused"
	if wrapped.Error() != expectedMsg {
		return fmt.Errorf("expected Error() to be %q, got %q", expectedMsg, wrapped.Error())
	}

	// 3. Wrapf preserves underlying root error retrievable via errors.Cause
	if cause := errors.Cause(wrapped); cause != rootErr {
		return fmt.Errorf("expected root cause %v, got %v", rootErr, cause)
	}

	// 4. Wrapf supports Go 1.13 error unwrapping via errors.Unwrap and errors.Is
	unwrapped := stderrors.Unwrap(wrapped)
	if unwrapped == nil || unwrapped.Error() != expectedMsg {
		return fmt.Errorf("expected first Unwrap to return withMessage error %q, got %v", expectedMsg, unwrapped)
	}
	if !stderrors.Is(wrapped, rootErr) {
		return fmt.Errorf("expected errors.Is(wrapped, rootErr) to be true")
	}

	// 5. Wrapf captures call site stack trace accessible via StackTrace() method
	tracer, ok := wrapped.(stackTracer)
	if !ok {
		return fmt.Errorf("expected wrapped error to implement stackTracer")
	}
	st := tracer.StackTrace()
	if len(st) == 0 {
		return fmt.Errorf("expected non-empty StackTrace from Wrapf")
	}

	// 6. Wrapf formats with %s and %v as colon-separated message, and %+v with multiline cause, message, and call site stack trace
	sFormatted := fmt.Sprintf("%s", wrapped)
	if sFormatted != expectedMsg {
		return fmt.Errorf("expected %%s to format as %q, got %q", expectedMsg, sFormatted)
	}
	vFormatted := fmt.Sprintf("%v", wrapped)
	if vFormatted != expectedMsg {
		return fmt.Errorf("expected %%v to format as %q, got %q", expectedMsg, vFormatted)
	}
	plusV := fmt.Sprintf("%+v", wrapped)
	if !strings.Contains(plusV, "connection refused") || !strings.Contains(plusV, "query failed for user alice on port 5432") {
		return fmt.Errorf("expected %%+v to contain cause and annotation, got %q", plusV)
	}
	if !strings.Contains(plusV, "contract.go") {
		return fmt.Errorf("expected %%+v to contain call site frame 'contract.go', got %q", plusV)
	}

	// 7. Wrapf supports nested chaining while preserving the original root cause
	chained := errors.Wrapf(wrapped, "operation failed after retry %d", 3)
	expectedChainedMsg := "operation failed after retry 3: query failed for user alice on port 5432: connection refused"
	if chained.Error() != expectedChainedMsg {
		return fmt.Errorf("expected chained Error() to be %q, got %q", expectedChainedMsg, chained.Error())
	}
	if cause := errors.Cause(chained); cause != rootErr {
		return fmt.Errorf("expected chained cause %v, got %v", rootErr, cause)
	}
	if !stderrors.Is(chained, rootErr) {
		return fmt.Errorf("expected errors.Is(chained, rootErr) to be true")
	}

	return nil
}