golang.org/x/tools v0.44.0: astutil.Cursor

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/go/ast/astutil.Cursor in pkg:golang/golang.org/x/tools@v0.44.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/tools@v0.44.0
Demonstrate these symbols/APIs:
  - golang.org/x/tools/go/ast/astutil.Cursor
Required runtime conditions:
  - ecosystem: golang
  - language: go
  - packageManager: go@1.26.6
  - runtime: go@1.26.6

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:04fbfc811a8e3a60079abcf03aac8a8068a84416f209361be50f8feefa747c91","contract":["Cursor.Node and Cursor.Parent return the current AST node and its enclosing parent node during traversal","Cursor.Name and Cursor.Index report the parent AST field name and slice element index","Cursor.Replace replaces an AST node with another node during AST traversal","Cursor.Delete removes an AST node from a slice of statements in a block","Cursor.InsertBefore and Cursor.InsertAfter insert sibling statements into an AST block"],"goal":"verify golang.org/x/tools/go/ast/astutil.Cursor in pkg:golang/golang.org/x/tools@v0.44.0","kind":"HOW","packages":["pkg:golang/golang.org/x/tools@v0.44.0"],"schemaVersion":1,"symbols":["golang.org/x/tools/go/ast/astutil.Cursor"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/golang.org/x/tools@v0.44.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/tools@v0.44.0","symbols":["golang.org/x/tools/go/ast/astutil.Cursor"],"verifierAdapter":"golang@1"}

module sample-astutil-cursor

go 1.26.6

require golang.org/x/tools v0.44.0

golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=

package main

import (
	"bytes"
	"fmt"
	"go/ast"
	"go/format"
	"go/parser"
	"go/token"

	"golang.org/x/tools/go/ast/astutil"
)

func main() {
	src := `package main

func greet() {
	msg := "hello"
	_ = msg
}
`
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "example.go", src, parser.ParseComments)
	if err != nil {
		panic(err)
	}

	// Use astutil.Apply and astutil.Cursor to replace identifier "msg" with "greeting"
	astutil.Apply(file, func(c *astutil.Cursor) bool {
		n := c.Node()
		if ident, ok := n.(*ast.Ident); ok && ident.Name == "msg" {
			c.Replace(ast.NewIdent("greeting"))
		}
		return true
	}, nil)

	var buf bytes.Buffer
	if err := format.Node(&buf, fset, file); err != nil {
		panic(err)
	}

	fmt.Println("Transformed code:")
	fmt.Println(buf.String())
}

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/tools/go/ast/astutil.Cursor in pkg:golang/golang.org/x/tools@v0.44.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/tools@v0.44.0"
  ],
  "symbols": [
    "golang.org/x/tools/go/ast/astutil.Cursor"
  ],
  "runtimeConditions": {
    "ecosystem": "golang",
    "language": "go",
    "packageManager": "go@1.26.6",
    "runtime": "go@1.26.6"
  }
}

package main

import (
	"bytes"
	"fmt"
	"go/ast"
	"go/format"
	"go/parser"
	"go/token"
	"os"
	"strings"

	"golang.org/x/tools/go/ast/astutil"
)

func main() {
	// Assertion 1: Cursor.Node and Cursor.Parent return the current AST node and its enclosing parent node during traversal
	{
		src := `package main
func targetFunc() {
	x := 42
	_ = x
}`
		fset := token.NewFileSet()
		file, err := parser.ParseFile(fset, "src.go", src, 0)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: ParseFile failed: %v\n", err)
			os.Exit(1)
		}

		foundFunc := false
		foundBlock := false

		astutil.Apply(file, func(c *astutil.Cursor) bool {
			if fn, ok := c.Node().(*ast.FuncDecl); ok {
				if fn.Name.Name == "targetFunc" {
					foundFunc = true
					if c.Parent() != file {
						fmt.Fprintf(os.Stderr, "FAIL: FuncDecl parent is not *ast.File\n")
						os.Exit(1)
					}
				}
			}
			if blk, ok := c.Node().(*ast.BlockStmt); ok {
				if fn, ok := c.Parent().(*ast.FuncDecl); ok && fn.Name.Name == "targetFunc" {
					foundBlock = true
					if c.Node() != blk {
						fmt.Fprintf(os.Stderr, "FAIL: BlockStmt Cursor.Node mismatch\n")
						os.Exit(1)
					}
				}
			}
			return true
		}, nil)

		if !foundFunc || !foundBlock {
			fmt.Fprintf(os.Stderr, "FAIL: did not find targetFunc (%v) or its block (%v)\n", foundFunc, foundBlock)
			os.Exit(1)
		}
	}

	// Assertion 2: Cursor.Name and Cursor.Index report the parent AST field name and slice element index
	{
		src := `package main
func first() {}
func second() {}`
		fset := token.NewFileSet()
		file, err := parser.ParseFile(fset, "src.go", src, 0)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: ParseFile failed: %v\n", err)
			os.Exit(1)
		}

		checkedFirst := false
		checkedSecond := false

		astutil.Apply(file, func(c *astutil.Cursor) bool {
			if fn, ok := c.Node().(*ast.FuncDecl); ok {
				if fn.Name.Name == "first" {
					checkedFirst = true
					if c.Name() != "Decls" || c.Index() != 0 {
						fmt.Fprintf(os.Stderr, "FAIL: first() name=%q index=%d, expected Decls/0\n", c.Name(), c.Index())
						os.Exit(1)
					}
				} else if fn.Name.Name == "second" {
					checkedSecond = true
					if c.Name() != "Decls" || c.Index() != 1 {
						fmt.Fprintf(os.Stderr, "FAIL: second() name=%q index=%d, expected Decls/1\n", c.Name(), c.Index())
						os.Exit(1)
					}
				}
			}
			return true
		}, nil)

		if !checkedFirst || !checkedSecond {
			fmt.Fprintf(os.Stderr, "FAIL: did not check first (%v) or second (%v)\n", checkedFirst, checkedSecond)
			os.Exit(1)
		}
	}

	// Assertion 3: Cursor.Replace replaces an AST node with another node during AST traversal
	{
		src := `package main
func run() {
	oldVar := 100
	_ = oldVar
}`
		fset := token.NewFileSet()
		file, err := parser.ParseFile(fset, "src.go", src, 0)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: ParseFile failed: %v\n", err)
			os.Exit(1)
		}

		replaceCount := 0
		astutil.Apply(file, func(c *astutil.Cursor) bool {
			if ident, ok := c.Node().(*ast.Ident); ok && ident.Name == "oldVar" {
				c.Replace(ast.NewIdent("newVar"))
				replaceCount++
			}
			return true
		}, nil)

		if replaceCount != 2 {
			fmt.Fprintf(os.Stderr, "FAIL: expected 2 replacements, got %d\n", replaceCount)
			os.Exit(1)
		}

		var buf bytes.Buffer
		if err := format.Node(&buf, fset, file); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: format.Node failed: %v\n", err)
			os.Exit(1)
		}
		res := buf.String()
		if strings.Contains(res, "oldVar") || !strings.Contains(res, "newVar") {
			fmt.Fprintf(os.Stderr, "FAIL: replacement not reflected in formatted code:\n%s\n", res)
			os.Exit(1)
		}
	}

	// Assertion 4: Cursor.Delete removes an AST node from a slice of statements in a block
	{
		src := `package main
func run() {
	keepFirst := 1
	removeThis := 2
	keepSecond := 3
	_, _ = keepFirst, keepSecond
}`
		fset := token.NewFileSet()
		file, err := parser.ParseFile(fset, "src.go", src, 0)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: ParseFile failed: %v\n", err)
			os.Exit(1)
		}

		deleted := false
		astutil.Apply(file, func(c *astutil.Cursor) bool {
			if assign, ok := c.Node().(*ast.AssignStmt); ok {
				for _, lhs := range assign.Lhs {
					if id, ok := lhs.(*ast.Ident); ok && id.Name == "removeThis" {
						c.Delete()
						deleted = true
						break
					}
				}
			}
			return true
		}, nil)

		if !deleted {
			fmt.Fprintf(os.Stderr, "FAIL: removeThis assign statement was not deleted\n")
			os.Exit(1)
		}

		var buf bytes.Buffer
		if err := format.Node(&buf, fset, file); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: format.Node failed: %v\n", err)
			os.Exit(1)
		}
		res := buf.String()
		if strings.Contains(res, "removeThis") {
			fmt.Fprintf(os.Stderr, "FAIL: removeThis still found in output:\n%s\n", res)
			os.Exit(1)
		}
	}

	// Assertion 5: Cursor.InsertBefore and Cursor.InsertAfter insert sibling statements into an AST block
	{
		src := `package main
func run() {
	pivot := 0
	_ = pivot
}`
		fset := token.NewFileSet()
		file, err := parser.ParseFile(fset, "src.go", src, 0)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: ParseFile failed: %v\n", err)
			os.Exit(1)
		}

		inserted := false
		astutil.Apply(file, func(c *astutil.Cursor) bool {
			if assign, ok := c.Node().(*ast.AssignStmt); ok {
				for _, lhs := range assign.Lhs {
					if id, ok := lhs.(*ast.Ident); ok && id.Name == "pivot" {
						beforeStmt := &ast.AssignStmt{
							Lhs: []ast.Expr{ast.NewIdent("beforePivot")},
							Tok: token.DEFINE,
							Rhs: []ast.Expr{&ast.BasicLit{Kind: token.INT, Value: "-1"}},
						}
						afterStmt := &ast.AssignStmt{
							Lhs: []ast.Expr{ast.NewIdent("afterPivot")},
							Tok: token.DEFINE,
							Rhs: []ast.Expr{&ast.BasicLit{Kind: token.INT, Value: "1"}},
						}
						c.InsertBefore(beforeStmt)
						c.InsertAfter(afterStmt)
						inserted = true
						break
					}
				}
			}
			return true
		}, nil)

		if !inserted {
			fmt.Fprintf(os.Stderr, "FAIL: pivot statement not found for insert\n")
			os.Exit(1)
		}

		var buf bytes.Buffer
		if err := format.Node(&buf, fset, file); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: format.Node failed: %v\n", err)
			os.Exit(1)
		}
		res := buf.String()
		if !strings.Contains(res, "beforePivot := -1") || !strings.Contains(res, "afterPivot := 1") {
			fmt.Fprintf(os.Stderr, "FAIL: inserted statements not found in output:\n%s\n", res)
			os.Exit(1)
		}
	}

	fmt.Println("PASS: Cursor contract passed")
}