integration_test.go

// Package main_test holds the end-to-end verification harness for the
// generator: for every C header under testdata/ it runs the CLI, then asserts
// hard invariants on the emitted Go -- including that the generated package
// really compiles against the real libffi bindings.
//
// The harness is deliberately coupled to nothing but the command line
// interface of the tool (-header/-output/-package/-lib), so it survives the
// ongoing rewrites of parser/ and generator/.
package main_test

import (
	"bytes"
	"errors"
	"fmt"
	"go/ast"
	"go/format"
	"go/parser"
	"go/scanner"
	"go/token"
	"os"
	"os/exec"
	"path/filepath"
	"sort"
	"strings"
	"sync"
	"testing"
)

// ---------------------------------------------------------------------------
// Temp module scaffolding shared by every compile check.
// ---------------------------------------------------------------------------

const (
	// ffi must be >= v0.5.1. Before that release the Go mirror of ffi_cif was a
	// single 32-byte struct on every architecture, but the aarch64 ABI defines
	// FFI_EXTRA_CIF_FIELDS (aarch64_flags, aarch64_nfixedargs), making the real
	// ffi_cif 40 bytes. On arm64, ffi_prep_cif therefore wrote 8 bytes past the
	// end of the allocation; once the neighbouring object was reused, ffi_call
	// marshalled from corrupted state. The observable symptom was float/double
	// arguments arriving as zero (a bogus nfixedargs makes every argument
	// variadic under Apple's ABI) and intermittent SIGSEGVs. v0.5.1 added
	// cif_arm64.go with the extra field. See runtime_test.go, which asserts the
	// Cif layout against the target ABI.
	ffiModule = "github.com/jupiterrider/ffi v0.7.0"
	sysModule = "golang.org/x/sys v0.28.0"
)

// goModTemplate is the go.mod written next to every generated package. The
// indirect purego requirement is what `go mod tidy` resolves to for the pinned
// ffi version; pinning it here keeps the build hermetic and offline.
const goModTemplate = `module ffigen.test/generated

go 1.25.6

require (
	` + ffiModule + `
	` + sysModule + `
)

require github.com/ebitengine/purego v0.10.0 // indirect
`

// goSumContents pins the hashes for the three modules above so the build never
// needs the network or the checksum database.
const goSumContents = `github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
github.com/jupiterrider/ffi v0.7.0 h1:RKsl6Ascal+3kyAqR5Qcbp83LceQMLc1VZbPfHWoNzs=
github.com/jupiterrider/ffi v0.7.0/go.mod h1:9dauhpOfNqrqk28fxuu0kkdeFtT9Qr4vbfigiuIXN7c=
golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
`

// preflightSource imports both dependencies and nothing else. If this does not
// build, the module cache is cold and the environment is offline; only then may
// a compile check be skipped.
const preflightSource = `package generated

import (
	"github.com/jupiterrider/ffi"
	"golang.org/x/sys/unix"
)

var _ = ffi.TypePointer
var _ = unix.BytePtrFromString
`

// buildEnv returns an environment that resolves modules strictly from the local
// module cache: no proxy, no checksum database, no network.
func buildEnv() []string {
	return append(os.Environ(),
		"GOFLAGS=-mod=mod",
		"GOPROXY=off",
		"GOSUMDB=off",
		"GOPRIVATE=*",
		"GONOSUMDB=*",
	)
}

// writeModule drops go.mod and go.sum into dir.
func writeModule(t *testing.T, dir string) {
	t.Helper()
	mustWrite(t, filepath.Join(dir, "go.mod"), goModTemplate)
	mustWrite(t, filepath.Join(dir, "go.sum"), goSumContents)
}

func mustWrite(t *testing.T, path, content string) {
	t.Helper()
	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
		t.Fatalf("write %s: %v", path, err)
	}
}

// runGoBuild runs `go build ./...` in dir and returns the combined output.
func runGoBuild(dir string) (string, error) {
	cmd := exec.Command("go", "build", "./...")
	cmd.Dir = dir
	cmd.Env = buildEnv()
	out, err := cmd.CombinedOutput()
	return string(out), err
}

// ---------------------------------------------------------------------------
// Shared, once-only setup: the CLI binary and the offline-module preflight.
// ---------------------------------------------------------------------------

var (
	cliOnce sync.Once
	cliPath string
	cliErr  error

	preflightOnce sync.Once
	preflightOut  string
	preflightErr  error
)

// repoRoot is the directory holding this test file.
func repoRoot(t *testing.T) string {
	t.Helper()
	wd, err := os.Getwd()
	if err != nil {
		t.Fatalf("getwd: %v", err)
	}
	return wd
}

// cliBinary builds the converter once per test run and returns its path.
// Building the CLI (rather than calling parser/generator directly) keeps this
// harness decoupled from the internal APIs, which are being rewritten.
func cliBinary(t *testing.T) string {
	t.Helper()
	cliOnce.Do(func() {
		dir, err := os.MkdirTemp("", "ffi-converter-bin")
		if err != nil {
			cliErr = err
			return
		}
		bin := filepath.Join(dir, "ffi-converter")
		cmd := exec.Command("go", "build", "-o", bin, ".")
		cmd.Dir = repoRoot(t)
		if out, err := cmd.CombinedOutput(); err != nil {
			cliErr = fmt.Errorf("building the converter failed:\n%s", out)
			return
		}
		cliPath = bin
	})
	if cliErr != nil {
		t.Fatalf("%v", cliErr)
	}
	return cliPath
}

// modulesAvailable reports whether a package importing ffi and x/sys/unix can
// be built offline from the local module cache. It is the ONLY thing allowed to
// turn a compile failure into a skip: once the preflight passes, any later
// build failure is a genuine defect in the generated code.
func modulesAvailable(t *testing.T) (bool, string) {
	t.Helper()
	preflightOnce.Do(func() {
		dir, err := os.MkdirTemp("", "ffi-preflight")
		if err != nil {
			preflightErr = err
			return
		}
		writeModule(t, dir)
		mustWrite(t, filepath.Join(dir, "preflight.go"), preflightSource)
		preflightOut, preflightErr = runGoBuild(dir)
	})
	if preflightErr != nil {
		return false, preflightOut
	}
	return true, ""
}

// ---------------------------------------------------------------------------
// Generation.
// ---------------------------------------------------------------------------

// generated is one run of the converter over one header.
type generated struct {
	header  string            // absolute path to the .h
	pkg     string            // Go package name used
	dir     string            // output directory (also a temp module)
	names   []string          // sorted list of emitted .go file names
	sources map[string]string // file name -> source
	files   map[string]*ast.File
	fset    *token.FileSet
	stdout  string
	stderr  string
}

// pkgNameFor turns a header base name into a legal, lower-case Go identifier.
func pkgNameFor(header string) string {
	base := strings.TrimSuffix(filepath.Base(header), filepath.Ext(header))
	var b strings.Builder
	for _, r := range base {
		switch {
		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
			b.WriteRune(r)
		case r >= 'A' && r <= 'Z':
			b.WriteRune(r + 32)
		}
	}
	name := b.String()
	if name == "" || (name[0] >= '0' && name[0] <= '9') {
		name = "hdr" + name
	}
	return name
}

// runConverter invokes the CLI on header, writing into a fresh temp dir.
func runConverter(t *testing.T, header string) *generated {
	t.Helper()

	pkg := pkgNameFor(header)
	dir := t.TempDir()

	cmd := exec.Command(cliBinary(t),
		"-header", header,
		"-output", dir,
		"-package", pkg,
		"-lib", pkg,
	)
	var stdout, stderr bytes.Buffer
	cmd.Stdout = &stdout
	cmd.Stderr = &stderr
	if err := cmd.Run(); err != nil {
		t.Fatalf("converter failed on %s: %v\nstdout:\n%s\nstderr:\n%s",
			filepath.Base(header), err, stdout.String(), stderr.String())
	}

	g := &generated{
		header:  header,
		pkg:     pkg,
		dir:     dir,
		sources: map[string]string{},
		files:   map[string]*ast.File{},
		fset:    token.NewFileSet(),
		// The output directory is a fresh temp dir on every run, so scrub it
		// out of the captured streams: only the tool's own ordering decisions
		// should be observable to TestDeterministicOutput.
		stdout: strings.ReplaceAll(stdout.String(), dir, "$OUT"),
		stderr: strings.ReplaceAll(stderr.String(), dir, "$OUT"),
	}

	entries, err := filepath.Glob(filepath.Join(dir, "*.go"))
	if err != nil {
		t.Fatalf("glob: %v", err)
	}
	sort.Strings(entries)
	for _, path := range entries {
		data, err := os.ReadFile(path)
		if err != nil {
			t.Fatalf("read %s: %v", path, err)
		}
		name := filepath.Base(path)
		g.names = append(g.names, name)
		g.sources[name] = string(data)
	}
	return g
}

// ---------------------------------------------------------------------------
// Invariants. Each is a named check run against every generated package.
// ---------------------------------------------------------------------------

type invariant struct {
	name string
	// check runs against one generated package. Checks may assume that
	// checkParses ran first (it populates g.files) and simply return early
	// when a file failed to parse.
	check func(t *testing.T, g *generated)
}

var invariants = []invariant{
	{"emits-files", checkEmitsFiles},
	{"parses", checkParses},
	{"gofmt-stable", checkGofmtStable},
	{"identifier-hygiene", checkIdentifierHygiene},
	{"unique-param-names", checkUniqueParamNames},
	{"compiles", checkCompiles},
}

func checkEmitsFiles(t *testing.T, g *generated) {
	if len(g.names) == 0 {
		t.Errorf("no Go files emitted for %s (a header the tool cannot support must still produce a diagnostic, not silence)", filepath.Base(g.header))
	}
}

// checkParses parses every emitted file with go/parser and caches the ASTs for
// the later checks.
func checkParses(t *testing.T, g *generated) {
	for _, name := range g.names {
		f, err := parser.ParseFile(g.fset, name, g.sources[name], parser.ParseComments|parser.SkipObjectResolution)
		if err != nil {
			t.Errorf("%s does not parse: %v\n%s", name, firstErrors(err), numbered(g.sources[name]))
			continue
		}
		g.files[name] = f
	}
}

// checkGofmtStable asserts format.Source is a no-op on every emitted file.
func checkGofmtStable(t *testing.T, g *generated) {
	for _, name := range g.names {
		src := g.sources[name]
		formatted, err := format.Source([]byte(src))
		if err != nil {
			// Already reported by checkParses; avoid duplicate noise.
			continue
		}
		if string(formatted) != src {
			t.Errorf("%s is not gofmt-stable; generated output must be run through go/format.Source\n%s",
				name, unifiedish(src, string(formatted)))
		}
	}
}

// goKeywords is the set of reserved words that may never appear as an emitted
// identifier.
var goKeywords = map[string]bool{
	"break": true, "case": true, "chan": true, "const": true, "continue": true,
	"default": true, "defer": true, "else": true, "fallthrough": true, "for": true,
	"func": true, "go": true, "goto": true, "if": true, "import": true,
	"interface": true, "map": true, "package": true, "range": true, "return": true,
	"select": true, "struct": true, "switch": true, "type": true, "var": true,
}

// checkIdentifierHygiene walks every declaration and asserts that no emitted
// identifier is a Go keyword, empty, or the blank identifier where a real name
// is required.
func checkIdentifierHygiene(t *testing.T, g *generated) {
	for _, name := range g.names {
		f := g.files[name]
		if f == nil {
			continue
		}
		ast.Inspect(f, func(n ast.Node) bool {
			var ids []*ast.Ident
			switch d := n.(type) {
			case *ast.FuncDecl:
				ids = append(ids, d.Name)
			case *ast.TypeSpec:
				ids = append(ids, d.Name)
			case *ast.ValueSpec:
				ids = append(ids, d.Names...)
			case *ast.Field:
				ids = append(ids, d.Names...)
			}
			for _, id := range ids {
				if id == nil {
					continue
				}
				switch {
				case id.Name == "":
					t.Errorf("%s: empty identifier emitted (see finding 1: toGoName(\"\") / toGoName(\"_\"))", name)
				case goKeywords[id.Name]:
					t.Errorf("%s: emitted identifier %q is a Go keyword (findings 2, 13)", name, id.Name)
				case strings.ContainsAny(id.Name, "* ."):
					t.Errorf("%s: emitted identifier %q contains an illegal character (findings 13, 15, 26)", name, id.Name)
				}
			}
			return true
		})
	}
}

// checkUniqueParamNames asserts no function signature repeats a parameter name
// and that no parameter collides with the generator's own locals.
func checkUniqueParamNames(t *testing.T, g *generated) {
	reserved := []string{"result", "resultPtr", "err", "lib"}

	for _, name := range g.names {
		f := g.files[name]
		if f == nil {
			continue
		}
		for _, decl := range f.Decls {
			fn, ok := decl.(*ast.FuncDecl)
			if !ok || fn.Type.Params == nil {
				continue
			}
			seen := map[string]bool{}
			for _, field := range fn.Type.Params.List {
				for _, id := range field.Names {
					if id.Name == "_" {
						continue
					}
					if seen[id.Name] {
						t.Errorf("%s: func %s has duplicate parameter %q (finding 3)", name, fn.Name.Name, id.Name)
					}
					seen[id.Name] = true
				}
			}
			// Only wrappers that actually declare the locals can collide;
			// checking every exported wrapper is the cheap conservative form.
			if !fn.Name.IsExported() || fn.Body == nil {
				continue
			}
			for _, r := range reserved {
				if seen[r] && declaresLocal(fn.Body, r) {
					t.Errorf("%s: func %s has a parameter %q that collides with a generated local of the same name (finding 4)",
						name, fn.Name.Name, r)
				}
			}
		}
	}
}

// declaresLocal reports whether body contains a `var r ...` or `r := ...` for
// the given name -- i.e. the parameter really is shadowed/redeclared.
func declaresLocal(body *ast.BlockStmt, target string) bool {
	found := false
	ast.Inspect(body, func(n ast.Node) bool {
		switch s := n.(type) {
		case *ast.AssignStmt:
			if s.Tok != token.DEFINE {
				return true
			}
			for _, lhs := range s.Lhs {
				if id, ok := lhs.(*ast.Ident); ok && id.Name == target {
					found = true
				}
			}
		case *ast.ValueSpec:
			for _, id := range s.Names {
				if id.Name == target {
					found = true
				}
			}
		}
		return !found
	})
	return found
}

// checkCompiles is the load-bearing invariant: assemble the emitted package
// into a module requiring the real ffi + x/sys and run `go build`.
func checkCompiles(t *testing.T, g *generated) {
	if len(g.names) == 0 {
		return
	}
	if ok, out := modulesAvailable(t); !ok {
		t.Skipf("SKIP (environment, not the generator): a package importing %s and %s cannot be built offline from the local module cache, so the compile check cannot run. Warm the cache with `go mod download` while online. Preflight output:\n%s",
			ffiModule, sysModule, out)
		return
	}

	writeModule(t, g.dir)
	out, err := runGoBuild(g.dir)
	if err != nil {
		t.Errorf("generated package does not compile: %v\n%s\n--- sources ---\n%s", err, out, g.dump())
	}
}

// ---------------------------------------------------------------------------
// The table-driven entry point.
// ---------------------------------------------------------------------------

// headers returns every C header in testdata/, sorted.
func headers(t *testing.T) []string {
	t.Helper()
	paths, err := filepath.Glob(filepath.Join(repoRoot(t), "testdata", "*.h"))
	if err != nil {
		t.Fatalf("glob testdata: %v", err)
	}
	if len(paths) == 0 {
		t.Fatal("no headers found in testdata/")
	}
	sort.Strings(paths)
	return paths
}

// TestGeneratedBindings runs every invariant against every header in testdata/.
func TestGeneratedBindings(t *testing.T) {
	for _, header := range headers(t) {
		t.Run(filepath.Base(header), func(t *testing.T) {
			g := runConverter(t, header)
			for _, inv := range invariants {
				t.Run(inv.name, func(t *testing.T) {
					inv.check(t, g)
				})
			}
		})
	}
}

// TestDeterministicOutput covers finding 20: main.go iterates a map, so output
// must nonetheless be byte-identical across runs.
func TestDeterministicOutput(t *testing.T) {
	for _, header := range headers(t) {
		t.Run(filepath.Base(header), func(t *testing.T) {
			a := runConverter(t, header)
			b := runConverter(t, header)

			if strings.Join(a.names, ",") != strings.Join(b.names, ",") {
				t.Fatalf("file set differs between runs: %v vs %v", a.names, b.names)
			}
			for _, name := range a.names {
				if a.sources[name] != b.sources[name] {
					t.Errorf("%s differs between two runs over the same header (finding 20)", name)
				}
			}
			if a.stdout != b.stdout {
				t.Errorf("CLI stdout is nondeterministic (finding 20):\n--- run 1 ---\n%s\n--- run 2 ---\n%s", a.stdout, b.stdout)
			}
		})
	}
}

// TestLibNameDerivation covers finding 21: deriving -lib from odd header paths
// must not yield an empty or nonsensical library name.
func TestLibNameDerivation(t *testing.T) {
	bin := cliBinary(t)

	cases := []struct {
		name       string
		headerName string
	}{
		{"dot-h-only", ".h"},
		{"no-extension", "plainheader"},
	}

	const src = "int32_t probe_fn(int32_t a);\n"

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			in := t.TempDir()
			header := filepath.Join(in, tc.headerName)
			mustWrite(t, header, src)

			out := t.TempDir()
			cmd := exec.Command(bin, "-header", header, "-output", out, "-package", "probe")
			combined, err := cmd.CombinedOutput()
			if err != nil {
				// A clean refusal is an acceptable outcome; a crash is not.
				if !strings.Contains(string(combined), "error") && !strings.Contains(string(combined), "warning") {
					t.Fatalf("converter failed without a diagnostic: %v\n%s", err, combined)
				}
				return
			}

			loader := filepath.Join(out, "loader.go")
			data, err := os.ReadFile(loader)
			if err != nil {
				t.Skipf("no loader.go emitted (%v); nothing to assert about the library name", err)
			}
			if strings.Contains(string(data), `"lib.so"`) || strings.Contains(string(data), `"lib/"`) ||
				strings.Contains(string(data), `""`) {
				t.Errorf("degenerate library name derived from header %q (finding 21):\n%s", tc.headerName, data)
			}
		})
	}
}

// ---------------------------------------------------------------------------
// Small reporting helpers.
// ---------------------------------------------------------------------------

func (g *generated) dump() string {
	var b strings.Builder
	for _, name := range g.names {
		fmt.Fprintf(&b, "==== %s ====\n%s\n", name, numbered(g.sources[name]))
	}
	return b.String()
}

// numbered prefixes each line with its number so parser/compiler positions in
// the failure message can be located.
func numbered(src string) string {
	var b strings.Builder
	for i, line := range strings.Split(src, "\n") {
		fmt.Fprintf(&b, "%4d| %s\n", i+1, line)
	}
	return b.String()
}

// firstErrors trims a scanner.ErrorList to its first few entries.
func firstErrors(err error) string {
	var list scanner.ErrorList
	if !errors.As(err, &list) {
		return err.Error()
	}
	const max = 5
	var parts []string
	for i, e := range list {
		if i == max {
			parts = append(parts, fmt.Sprintf("... and %d more", len(list)-max))
			break
		}
		parts = append(parts, e.Error())
	}
	return strings.Join(parts, "; ")
}

// unifiedish reports the first differing line between got and want.
func unifiedish(got, want string) string {
	g := strings.Split(got, "\n")
	w := strings.Split(want, "\n")
	for i := 0; i < len(g) && i < len(w); i++ {
		if g[i] != w[i] {
			return fmt.Sprintf("first difference at line %d:\n  got:  %q\n  want: %q", i+1, g[i], w[i])
		}
	}
	return fmt.Sprintf("output differs in length: got %d lines, want %d", len(g), len(w))
}

// ---------------------------------------------------------------------------
// Real system headers.
// ---------------------------------------------------------------------------

// systemHeaderDirs are the usual homes of installed C headers. Only the ones
// that exist on this machine are used; an absent header is a skip.
func systemHeaderDirs() []string {
	dirs := []string{"/usr/include", "/usr/local/include", "/opt/homebrew/include"}

	if out, err := exec.Command("xcrun", "--show-sdk-path").Output(); err == nil {
		dirs = append(dirs, filepath.Join(strings.TrimSpace(string(out)), "usr", "include"))
	}

	return dirs
}

// findSystemHeader returns the first existing path for name, or "".
func findSystemHeader(name string) string {
	for _, dir := range systemHeaderDirs() {
		path := filepath.Join(dir, name)
		if _, err := os.Stat(path); err == nil {
			return path
		}
	}

	return ""
}

// TestRealSystemHeaders is the smoke test that would have caught finding S11.
// Almost every real C library header wraps its entire API in
//
//	#ifdef __cplusplus
//	extern "C" {
//	#endif
//
// The lexer drops the directives but not the block, and the parser used to
// classify `extern "C" {` as a function definition with a body -- so it skipped
// the braced region, i.e. the whole API. zlib.h, sqlite3.h and ares.h all
// emitted ZERO wrappers while every testdata header (none of which used the
// idiom) passed. Asserting a plausible wrapper count against real headers is
// the check the synthetic corpus structurally could not make.
func TestRealSystemHeaders(t *testing.T) {
	tests := []struct {
		name    string
		header  string
		minFns  int
		wantFns []string
	}{
		{"sqlite3.h", "sqlite3.h", 100, []string{"func Sqlite3Close(", "func Sqlite3Libversion("}},
		{"ares.h", "ares.h", 20, []string{"func AresLibraryInit("}},

		// zlib.h is listed for the linkage-block assertion only. Its classic
		// spelling wraps every prototype in the OF((...)) macro, which needs
		// real preprocessor expansion; that is a separate, out-of-scope gap, so
		// no wrapper count is asserted for it.
		{"zlib.h", "zlib.h", 0, nil},
	}

	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			path := findSystemHeader(tc.header)
			if path == "" {
				t.Skipf("%s is not installed on this machine", tc.header)
			}

			g := runConverter(t, path)

			// The S11 assertion proper, and the one that holds for every real
			// header: the linkage-specification block must never be mistaken
			// for a function definition with a body, because that skips the
			// entire API in one diagnostic.
			if strings.Contains(g.stderr, `skipped function definition "extern`) {
				t.Errorf("finding S11: the extern \"C\" block of %s was skipped as a function definition, "+
					"which discards every declaration inside it:\n%s", path, g.stderr)
			}

			src := g.sources["functions.go"]
			if got := strings.Count(src, "\nfunc "); got < tc.minFns {
				t.Errorf("finding S11: %s produced %d generated functions, want at least %d.\nstderr:\n%s",
					path, got, tc.minFns, g.stderr)
			}
			for _, want := range tc.wantFns {
				if !strings.Contains(src, want) {
					t.Errorf("finding S11: %s produced no %q", path, want)
				}
			}
		})
	}
}