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

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

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:d23d884d7d542d51693d9f789ab6046ca5fb2877e4403e09ef855d0dfd49efb1","contract":["errors.StackTrace represents call sites as a slice of Frame obtained from errors created with errors.New or errors.WithStack","errors.StackTrace formats source file names as a slice when formatted with %s","errors.StackTrace formats source file and line numbers when formatted with %v","errors.StackTrace formats function names, source paths, and line numbers across newlines when formatted with %+v","errors.Frame in StackTrace implements encoding.TextMarshaler through MarshalText"],"goal":"verify github.com/pkg/errors.StackTrace 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.StackTrace"]},"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.StackTrace"],"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"

	"github.com/pkg/errors"
)

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

// performAction simulates an operation that encounters an error with stack trace.
func performAction() error {
	return errors.New("operation failed")
}

func main() {
	err := performAction()
	if tracer, ok := err.(stackTracer); ok {
		st := tracer.StackTrace()
		fmt.Printf("Stack trace frame count: %d\n", len(st))
		if len(st) > 0 {
			fmt.Printf("Top frame: %v\n", st[0])
		}
	}
}

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

package main

import (
	"encoding"
	"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.StackTrace contract assertions passed successfully.")
}

func runContract() error {
	// 1. errors.StackTrace represents call sites as a slice of Frame obtained from errors created with errors.New or errors.WithStack
	errNew := errors.New("base failure")
	tracerNew, ok := errNew.(stackTracer)
	if !ok {
		return fmt.Errorf("expected errors.New to implement stackTracer")
	}
	stNew := tracerNew.StackTrace()
	if len(stNew) == 0 {
		return fmt.Errorf("expected non-empty StackTrace from errors.New")
	}

	plainErr := fmt.Errorf("plain standard error")
	errWithStack := errors.WithStack(plainErr)
	tracerWithStack, ok := errWithStack.(stackTracer)
	if !ok {
		return fmt.Errorf("expected errors.WithStack to implement stackTracer")
	}
	stWithStack := tracerWithStack.StackTrace()
	if len(stWithStack) == 0 {
		return fmt.Errorf("expected non-empty StackTrace from errors.WithStack")
	}

	// 2. errors.StackTrace formats source file names as a slice when formatted with %s
	sFormatted := fmt.Sprintf("%s", stNew)
	if !strings.HasPrefix(sFormatted, "[") || !strings.HasSuffix(sFormatted, "]") || !strings.Contains(sFormatted, "contract.go") {
		return fmt.Errorf("expected StackTrace formatted with %%s to be slice format containing file names, got: %s", sFormatted)
	}

	// 3. errors.StackTrace formats source file and line numbers when formatted with %v
	vFormatted := fmt.Sprintf("%v", stNew)
	if !strings.HasPrefix(vFormatted, "[") || !strings.HasSuffix(vFormatted, "]") || !strings.Contains(vFormatted, "contract.go:") {
		return fmt.Errorf("expected StackTrace formatted with %%v to contain file:line pairs, got: %s", vFormatted)
	}

	// 4. errors.StackTrace formats function names, source paths, and line numbers across newlines when formatted with %+v
	plusVFormatted := fmt.Sprintf("%+v", stNew)
	if !strings.Contains(plusVFormatted, "\n") || !strings.Contains(plusVFormatted, "\t") || !strings.Contains(plusVFormatted, "contract.go:") {
		return fmt.Errorf("expected StackTrace formatted with %%+v to contain newlines, tabs, and file:line, got: %s", plusVFormatted)
	}

	// 5. errors.Frame in StackTrace implements encoding.TextMarshaler through MarshalText
	topFrame := stNew[0]
	var _ encoding.TextMarshaler = topFrame
	textBytes, err := topFrame.MarshalText()
	if err != nil {
		return fmt.Errorf("expected Frame.MarshalText to succeed, got: %v", err)
	}
	textStr := string(textBytes)
	if !strings.Contains(textStr, "contract.go:") {
		return fmt.Errorf("expected Frame.MarshalText output to contain file:line, got: %s", textStr)
	}

	return nil
}