golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1: xerrors error wrapping and chain inspection with Errorf and Is

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: xerrors error wrapping and chain inspection with Errorf and Is
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/xerrors@v0.0.0-20200804184101-5ec99f83aff1
Demonstrate these symbols/APIs:
  - xerrors.Errorf
  - xerrors.Is

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:0a1a588dc9ac09704199441a0d0ff776494db12f6f1a0bfc6d440c4f7d0d647e","contract":["xerrors.New creates distinct non-nil errors with expected message","xerrors.Errorf with %w wraps an inner error and includes formatted text","xerrors.Is matches direct errors and unwraps nested error chains created by xerrors.Errorf","xerrors.Is returns false when target is not present in the error chain","xerrors.Errorf preserves error message across multiple wrapping levels"],"goal":"xerrors error wrapping and chain inspection with Errorf and Is","kind":"HOW","packages":["pkg:golang/golang.org/x/xerrors@v0.0.0-20200804184101-5ec99f83aff1"],"schemaVersion":1,"symbols":["xerrors.Errorf","xerrors.Is"]},"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/xerrors@v0.0.0-20200804184101-5ec99f83aff1"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/xerrors@v0.0.0-20200804184101-5ec99f83aff1","symbols":["xerrors.Errorf","xerrors.Is"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.22.0

require golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1

golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

package main

import (
	"fmt"
	"os"

	"golang.org/x/xerrors"
)

var (
	// ErrNotFound indicates a requested resource was not found.
	ErrNotFound = xerrors.New("resource not found")
	// ErrPermission indicates an unauthorized access attempt.
	ErrPermission = xerrors.New("permission denied")
)

// WrapDatabaseOp wraps a database-level error with operation context using xerrors.Errorf.
func WrapDatabaseOp(operation string, err error) error {
	if err == nil {
		return nil
	}
	return xerrors.Errorf("database operation %s: %w", operation, err)
}

// WrapServiceOp wraps a service-level error with additional context using xerrors.Errorf.
func WrapServiceOp(service string, err error) error {
	if err == nil {
		return nil
	}
	return xerrors.Errorf("service %s: %w", service, err)
}

// CheckErrorMatches checks whether target exists within err's wrap chain using xerrors.Is.
func CheckErrorMatches(err, target error) bool {
	return xerrors.Is(err, target)
}

func main() {
	dbErr := WrapDatabaseOp("queryUser", ErrNotFound)
	svcErr := WrapServiceOp("UserService", dbErr)

	fmt.Printf("Full error chain: %v\n", svcErr)

	if CheckErrorMatches(svcErr, ErrNotFound) {
		fmt.Println("Matched ErrNotFound in error chain")
	} else {
		fmt.Fprintf(os.Stderr, "Expected ErrNotFound match\n")
		os.Exit(1)
	}

	if CheckErrorMatches(svcErr, ErrPermission) {
		fmt.Fprintf(os.Stderr, "Unexpected ErrPermission match\n")
		os.Exit(1)
	} else {
		fmt.Println("Correctly did not match ErrPermission")
	}
}

{
  "schemaVersion": 1,
  "goal": "xerrors error wrapping and chain inspection with Errorf and Is",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/xerrors@v0.0.0-20200804184101-5ec99f83aff1"
  ],
  "symbols": [
    "xerrors.Errorf",
    "xerrors.Is"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	"golang.org/x/xerrors"
)

func main() {
	// Assertion 1: xerrors.New creates distinct non-nil errors with expected message
	errRoot := xerrors.New("root cause error")
	if errRoot == nil {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.New returned nil\n")
		os.Exit(1)
	}
	if errRoot.Error() != "root cause error" {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.New message mismatch: got %q, want %q\n", errRoot.Error(), "root cause error")
		os.Exit(1)
	}

	errOther := xerrors.New("other error")
	if xerrors.Is(errRoot, errOther) {
		fmt.Fprintf(os.Stderr, "FAIL: distinct xerrors.New instances unexpectedly matched\n")
		os.Exit(1)
	}

	// Assertion 2: xerrors.Errorf with %w wraps an inner error and includes formatted text
	errWrapped := xerrors.Errorf("layer 1 (%s): %w", "context", errRoot)
	if errWrapped == nil {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Errorf returned nil\n")
		os.Exit(1)
	}
	expectedMsg := "layer 1 (context): root cause error"
	if errWrapped.Error() != expectedMsg {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Errorf message mismatch: got %q, want %q\n", errWrapped.Error(), expectedMsg)
		os.Exit(1)
	}

	// Assertion 3: xerrors.Is matches direct errors and unwraps nested error chains created by xerrors.Errorf
	errDeep := xerrors.Errorf("layer 2: %w", errWrapped)
	if !xerrors.Is(errDeep, errRoot) {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Is failed to find root error in 2-level chain\n")
		os.Exit(1)
	}
	if !xerrors.Is(errDeep, errWrapped) {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Is failed to find intermediate error in chain\n")
		os.Exit(1)
	}
	if !xerrors.Is(errDeep, errDeep) {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Is failed on self comparison\n")
		os.Exit(1)
	}

	// Assertion 4: xerrors.Is returns false when target is not present in the error chain
	unrelatedErr := xerrors.New("unrelated error")
	if xerrors.Is(errDeep, unrelatedErr) {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Is matched unrelated error\n")
		os.Exit(1)
	}
	if xerrors.Is(errDeep, nil) {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Is matched nil target\n")
		os.Exit(1)
	}

	// Assertion 5: xerrors.Errorf preserves error message across multiple wrapping levels
	if !strings.Contains(errDeep.Error(), "layer 2: layer 1 (context): root cause error") {
		fmt.Fprintf(os.Stderr, "FAIL: xerrors.Errorf multi-level message mismatch: got %q\n", errDeep.Error())
		os.Exit(1)
	}

	fmt.Println("PASS: pkg:golang/golang.org/x/xerrors@v0.0.0-20200804184101-5ec99f83aff1 contract passed")
}