golang.org/x/tools v0.1.1: cfg.CFG

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/cfg.CFG in pkg:golang/golang.org/x/tools@v0.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/tools@v0.1.1
Demonstrate these symbols/APIs:
  - golang.org/x/tools/go/cfg.CFG

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.

package cfganalyzer

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

	"golang.org/x/tools/go/cfg"
)

// ParseAndBuildCFG parses a Go source code string and builds a *cfg.CFG for the first function.
func ParseAndBuildCFG(src string) (*cfg.CFG, *token.FileSet, error) {
	fset := token.NewFileSet()
	f, err := parser.ParseFile(fset, "src.go", src, 0)
	if err != nil {
		return nil, nil, fmt.Errorf("parsing failed: %w", err)
	}

	for _, decl := range f.Decls {
		if fn, ok := decl.(*ast.FuncDecl); ok && fn.Body != nil {
			g := cfg.New(fn.Body, func(call *ast.CallExpr) bool {
				if id, ok := call.Fun.(*ast.Ident); ok && id.Name == "panic" {
					return false
				}
				return true
			})
			return g, fset, nil
		}
	}
	return nil, nil, fmt.Errorf("no function declaration with body found")
}

// LiveBlocks returns all blocks in the CFG that are reachable (Live == true).
func LiveBlocks(g *cfg.CFG) []*cfg.Block {
	if g == nil {
		return nil
	}
	var live []*cfg.Block
	for _, b := range g.Blocks {
		if b.Live {
			live = append(live, b)
		}
	}
	return live
}

// DeadBlocks returns all blocks in the CFG that are unreachable (Live == false).
func DeadBlocks(g *cfg.CFG) []*cfg.Block {
	if g == nil {
		return nil
	}
	var dead []*cfg.Block
	for _, b := range g.Blocks {
		if !b.Live {
			dead = append(dead, b)
		}
	}
	return dead
}

// HasBranching reports whether any block in the CFG has more than one successor.
func HasBranching(g *cfg.CFG) bool {
	if g == nil {
		return false
	}
	for _, b := range g.Blocks {
		if len(b.Succs) > 1 {
			return true
		}
	}
	return false
}

{"case":{"caseId":"case:sha256:d8a188abdbe9e5b46e56c1f0ade823e37a93299a897159d09213c6220f76f24b","contract":["CFG.Blocks contains basic blocks representing control flow with block 0 as entry","CFG.Format renders a formatted string representation of basic blocks and successors","CFG represents conditional branching with multiple successor blocks from a decision block","CFG marks entry-reachable basic blocks as Live","CFG marks unreachable code following an unconditional return or panic as not Live","Block.Return returns the terminating return statement of a block or nil if absent"],"goal":"verify golang.org/x/tools/go/cfg.CFG in pkg:golang/golang.org/x/tools@v0.1.1","kind":"HOW","packages":["pkg:golang/golang.org/x/tools@v0.1.1"],"schemaVersion":1,"symbols":["golang.org/x/tools/go/cfg.CFG"]},"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.1.1"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/tools@v0.1.1","symbols":["golang.org/x/tools/go/cfg.CFG"],"verifierAdapter":"golang@1"}

module example.com/cfg-sample

go 1.21

require golang.org/x/tools v0.1.1

golang.org/x/tools v0.1.1 h1:wGiQel/hW0NnEkJUk8lbzkX2gFJU6PFxf1v5OlCfuOs=
golang.org/x/tools v0.1.1/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk=

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/tools/go/cfg.CFG in pkg:golang/golang.org/x/tools@v0.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/tools@v0.1.1"
  ],
  "symbols": [
    "golang.org/x/tools/go/cfg.CFG"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	cfganalyzer "example.com/cfg-sample"
)

func main() {
	if err := runContractTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("PASS: CFG contract passed")
}

func runContractTests() error {
	// 1. CFG.Blocks contains basic blocks representing control flow with block 0 as entry
	seqSrc := `package p
func linear() int {
	x := 10
	y := 20
	return x + y
}`
	gSeq, fsetSeq, err := cfganalyzer.ParseAndBuildCFG(seqSrc)
	if err != nil {
		return fmt.Errorf("linear parse failed: %w", err)
	}
	if gSeq == nil || len(gSeq.Blocks) == 0 {
		return fmt.Errorf("expected non-empty CFG.Blocks")
	}
	if gSeq.Blocks[0].Index != 0 {
		return fmt.Errorf("expected entry block index 0, got %d", gSeq.Blocks[0].Index)
	}
	if !gSeq.Blocks[0].Live {
		return fmt.Errorf("expected entry block to be Live")
	}

	// 2. CFG.Format renders a formatted string representation of basic blocks and successors
	formatted := gSeq.Format(fsetSeq)
	if !strings.Contains(formatted, ".0:") {
		return fmt.Errorf("Format output missing entry block marker: %q", formatted)
	}

	// 3. CFG represents conditional branching with multiple successor blocks from a decision block
	branchSrc := `package p
func branch(v int) string {
	if v > 0 {
		return "pos"
	}
	return "non-pos"
}`
	gBranch, fsetBranch, err := cfganalyzer.ParseAndBuildCFG(branchSrc)
	if err != nil {
		return fmt.Errorf("branch parse failed: %w", err)
	}
	if !cfganalyzer.HasBranching(gBranch) {
		return fmt.Errorf("expected branching in CFG for if statement")
	}
	formattedBranch := gBranch.Format(fsetBranch)
	if !strings.Contains(formattedBranch, "succs:") {
		return fmt.Errorf("expected 'succs:' in formatted branching CFG")
	}

	// 4. CFG marks entry-reachable basic blocks as Live
	liveBlocks := cfganalyzer.LiveBlocks(gBranch)
	if len(liveBlocks) == 0 {
		return fmt.Errorf("expected live blocks in branching CFG")
	}
	for _, b := range liveBlocks {
		if !b.Live {
			return fmt.Errorf("block %d reported in liveBlocks but Live is false", b.Index)
		}
	}

	// 5. CFG marks unreachable code following an unconditional return or panic as not Live
	deadSrc := `package p
func withDeadCode() int {
	return 42
	println("unreachable dead code")
}`
	gDead, _, err := cfganalyzer.ParseAndBuildCFG(deadSrc)
	if err != nil {
		return fmt.Errorf("dead code parse failed: %w", err)
	}
	deadBlocks := cfganalyzer.DeadBlocks(gDead)
	if len(deadBlocks) == 0 {
		return fmt.Errorf("expected at least one dead block after return statement")
	}

	// 6. Block.Return returns the terminating return statement of a block or nil if absent
	var foundReturn bool
	for _, b := range gSeq.Blocks {
		ret := b.Return()
		if ret != nil {
			foundReturn = true
		}
	}
	if !foundReturn {
		return fmt.Errorf("expected at least one block with non-nil Return()")
	}

	return nil
}