golang.org/x/tools v0.31.0: txtar.Archive

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 golang.org/x/tools/txtar.Archive in pkg:golang/golang.org/x/tools@v0.31.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/tools@v0.31.0
Demonstrate these symbols/APIs:
  - golang.org/x/tools/txtar.Archive

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:0742bc5b74c9d2b7724497711cab47e0105f68b7a10b31b55bed55fd8e161490","contract":["txtar.Archive struct holds Comment byte slice and Files slice","txtar.Format serializes Archive with Comment and Files to formatted txtar bytes","txtar.Parse parses formatted txtar bytes into Archive preserving Comment and Files","txtar.Parse handles empty archive data returning empty Comment and empty Files","txtar.Parse preserves multiple files and their file names and data contents in order","txtar.Format followed by txtar.Parse roundtrips Archive data accurately","txtar.Archive with empty comment formats files with standard header delimiters"],"goal":"verify golang.org/x/tools/txtar.Archive in pkg:golang/golang.org/x/tools@v0.31.0","kind":"HOW","packages":["pkg:golang/golang.org/x/tools@v0.31.0"],"schemaVersion":1,"symbols":["golang.org/x/tools/txtar.Archive"]},"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/tools@v0.31.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/tools@v0.31.0","symbols":["golang.org/x/tools/txtar.Archive"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.23.0

require golang.org/x/tools v0.31.0

golang.org/x/tools v0.31.0 h1:0EedkvKDbh+qistFTd0Bcwe/YLh4vHwWEkiI0toFIBU=
golang.org/x/tools v0.31.0/go.mod h1:naFTU+Cev749tSJRXJlna0T3WxKvb1kWEx15xA4SdmQ=

package main

import (
	"fmt"

	"golang.org/x/tools/txtar"
)

func main() {
	// Create an archive with comment and files
	archive := &txtar.Archive{
		Comment: []byte("This is a txtar archive comment\nsecond line of comment\n"),
		Files: []txtar.File{
			{
				Name: "hello.txt",
				Data: []byte("Hello, txtar world!\n"),
			},
			{
				Name: "config/app.json",
				Data: []byte("{\"status\": \"ok\"}\n"),
			},
		},
	}

	// Format archive into txtar formatted bytes
	data := txtar.Format(archive)
	fmt.Printf("Formatted txtar archive (%d bytes):\n%s\n", len(data), string(data))

	// Parse archive back from bytes
	parsed := txtar.Parse(data)
	fmt.Printf("Parsed archive comment: %q\n", string(parsed.Comment))
	fmt.Printf("Parsed %d files:\n", len(parsed.Files))
	for i, f := range parsed.Files {
		fmt.Printf("  File %d: %s (%d bytes): %q\n", i+1, f.Name, len(f.Data), string(f.Data))
	}
}

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/tools/txtar.Archive in pkg:golang/golang.org/x/tools@v0.31.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/tools@v0.31.0"
  ],
  "symbols": [
    "golang.org/x/tools/txtar.Archive"
  ]
}

package main

import (
	"bytes"
	"fmt"
	"os"

	"golang.org/x/tools/txtar"
)

func main() {
	// 1. txtar.Archive struct holds Comment byte slice and Files slice
	archive := &txtar.Archive{
		Comment: []byte("archive comment\n"),
		Files: []txtar.File{
			{Name: "file1.txt", Data: []byte("content 1\n")},
			{Name: "file2.txt", Data: []byte("content 2\n")},
		},
	}
	if !bytes.Equal(archive.Comment, []byte("archive comment\n")) {
		fmt.Fprintf(os.Stderr, "Archive Comment mismatch\n")
		os.Exit(1)
	}
	if len(archive.Files) != 2 || archive.Files[0].Name != "file1.txt" || !bytes.Equal(archive.Files[0].Data, []byte("content 1\n")) {
		fmt.Fprintf(os.Stderr, "Archive Files mismatch\n")
		os.Exit(1)
	}

	// 2. txtar.Format serializes Archive with Comment and Files to formatted txtar bytes
	formatted := txtar.Format(archive)
	expectedFormatted := "archive comment\n-- file1.txt --\ncontent 1\n-- file2.txt --\ncontent 2\n"
	if !bytes.Equal(formatted, []byte(expectedFormatted)) {
		fmt.Fprintf(os.Stderr, "txtar.Format output mismatch: got %q, want %q\n", string(formatted), expectedFormatted)
		os.Exit(1)
	}

	// 3. txtar.Parse parses formatted txtar bytes into Archive preserving Comment and Files
	parsed := txtar.Parse(formatted)
	if parsed == nil {
		fmt.Fprintf(os.Stderr, "txtar.Parse returned nil\n")
		os.Exit(1)
	}
	if !bytes.Equal(parsed.Comment, archive.Comment) {
		fmt.Fprintf(os.Stderr, "Parsed Comment mismatch: got %q, want %q\n", string(parsed.Comment), string(archive.Comment))
		os.Exit(1)
	}
	if len(parsed.Files) != 2 {
		fmt.Fprintf(os.Stderr, "Parsed Files count mismatch: got %d, want 2\n", len(parsed.Files))
		os.Exit(1)
	}
	if parsed.Files[0].Name != "file1.txt" || !bytes.Equal(parsed.Files[0].Data, []byte("content 1\n")) {
		fmt.Fprintf(os.Stderr, "Parsed File 0 mismatch\n")
		os.Exit(1)
	}
	if parsed.Files[1].Name != "file2.txt" || !bytes.Equal(parsed.Files[1].Data, []byte("content 2\n")) {
		fmt.Fprintf(os.Stderr, "Parsed File 1 mismatch\n")
		os.Exit(1)
	}

	// 4. txtar.Parse handles empty archive data returning empty Comment and empty Files
	emptyParsed := txtar.Parse([]byte(""))
	if emptyParsed == nil {
		fmt.Fprintf(os.Stderr, "txtar.Parse of empty byte slice returned nil\n")
		os.Exit(1)
	}
	if len(emptyParsed.Comment) != 0 || len(emptyParsed.Files) != 0 {
		fmt.Fprintf(os.Stderr, "Empty parse should have 0 comment and 0 files, got comment len %d, files len %d\n", len(emptyParsed.Comment), len(emptyParsed.Files))
		os.Exit(1)
	}

	// 5. txtar.Parse preserves multiple files and their file names and data contents in order
	rawTxtar := []byte("-- a.txt --\nfirst\n-- b/c.txt --\nsecond line 1\nsecond line 2\n")
	parsedRaw := txtar.Parse(rawTxtar)
	if len(parsedRaw.Files) != 2 {
		fmt.Fprintf(os.Stderr, "ParseRaw files count mismatch: got %d, want 2\n", len(parsedRaw.Files))
		os.Exit(1)
	}
	if parsedRaw.Files[0].Name != "a.txt" || !bytes.Equal(parsedRaw.Files[0].Data, []byte("first\n")) {
		fmt.Fprintf(os.Stderr, "ParseRaw file 0 mismatch: %s\n", parsedRaw.Files[0].Name)
		os.Exit(1)
	}
	if parsedRaw.Files[1].Name != "b/c.txt" || !bytes.Equal(parsedRaw.Files[1].Data, []byte("second line 1\nsecond line 2\n")) {
		fmt.Fprintf(os.Stderr, "ParseRaw file 1 mismatch: %s\n", parsedRaw.Files[1].Name)
		os.Exit(1)
	}

	// 6. txtar.Format followed by txtar.Parse roundtrips Archive data accurately
	roundtripFormatted := txtar.Format(parsedRaw)
	roundtripParsed := txtar.Parse(roundtripFormatted)
	if !bytes.Equal(roundtripParsed.Comment, parsedRaw.Comment) {
		fmt.Fprintf(os.Stderr, "Roundtrip comment mismatch\n")
		os.Exit(1)
	}
	if len(roundtripParsed.Files) != len(parsedRaw.Files) {
		fmt.Fprintf(os.Stderr, "Roundtrip files len mismatch\n")
		os.Exit(1)
	}
	for i := range parsedRaw.Files {
		if roundtripParsed.Files[i].Name != parsedRaw.Files[i].Name || !bytes.Equal(roundtripParsed.Files[i].Data, parsedRaw.Files[i].Data) {
			fmt.Fprintf(os.Stderr, "Roundtrip file %d mismatch\n", i)
			os.Exit(1)
		}
	}

	// 7. txtar.Archive with empty comment formats files with standard header delimiters
	noCommentArchive := &txtar.Archive{
		Files: []txtar.File{
			{Name: "only.txt", Data: []byte("content\n")},
		},
	}
	noCommentFormatted := txtar.Format(noCommentArchive)
	expectedNoComment := "-- only.txt --\ncontent\n"
	if !bytes.Equal(noCommentFormatted, []byte(expectedNoComment)) {
		fmt.Fprintf(os.Stderr, "NoComment format mismatch: got %q, want %q\n", string(noCommentFormatted), expectedNoComment)
		os.Exit(1)
	}

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