feat(ffi): automatically generate cgo pragma declarations (#1784)

## Why this should be merged

Closes: #1774

## How this works

This change adds a `go generate` program to parse the go source files
for `C.func(...)` calls and injects the relevant `#cgo` pragma comments
into those files. This also removes any previous pragmas.

Also added is a check to ensure that each c function has at most 1
callsite. While technically out of scope, it was necessary to ensure we
don't inject multiple pragmas. However, it is also unexpected if we were
to invoke a c function from two different places.

### Why not in Rust?

Go already has the proper tools to parse itself.

## How this was tested

The `ffi-check-go-generate` job was added to the CI workflow to ensure
that `go generate` does not produce any changes. It will fail very early
if so.


https://github.com/ava-labs/firewood/actions/runs/23062649367/job/66993031048?pr=1784#step:3:202

## Breaking Changes

n/a

---------

Signed-off-by: Joachim Brandon LeBlanc <brandon@leblanc.codes>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: demosdemon

.github/workflows/ci.yaml

@@ -224,8 +224,22 @@ jobs:
       - name: doc generation
         run: RUSTDOCFLAGS="-D warnings" cargo doc --locked --document-private-items --no-deps
 
+  ffi-check-go-generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Check `go generate` for changes
+        working-directory: ffi
+        run: |
+          go generate
+          if [[ -n $(git status --porcelain) ]]; then
+            echo "go generate resulted in changes to tracked files. Please commit these changes."
+            git --no-pager diff
+            exit 1
+          fi
+
   ffi:
-    needs: build
+    needs: [build, ffi-check-go-generate]
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:

ffi/firewood.go

@@ -6,7 +6,8 @@
 // [Firewood]: https://github.com/ava-labs/firewood
 package ffi
 
-//go:generate go run generate_cgo.go
+//go:generate go run ./gen/update-cgo-ldflags
+//go:generate go run ./gen/update-cgo-pragmas
 
 // // Note that -lm is required on Linux but not on Mac.
 // // FIREWOOD_CGO_BEGIN_STATIC_LIBS

ffi/generate_cgo.go ffi/gen/update-cgo-ldflags/main.goffi/generate_cgo.go renamed to ffi/gen/update-cgo-ldflags/main.go

@@ -1,8 +1,6 @@
 // Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
 // See the file LICENSE.md for licensing terms.
 
-//go:build ignore
-
 // go generate script
 //
 // This script fixes up a go file to enable/disable the correct cgo directives,
@@ -41,10 +39,6 @@ import (
 	"strings"
 )
 
-const (
-	defaultMode = "LOCAL_LIBS"
-)
-
 var errGoFileNotSet = errors.New("GOFILE is not set")
 
 func main() {
@@ -81,6 +75,8 @@ func getTargetFile() (string, error) {
 }
 
 func changeCgoDirectivesForFile(targetMode string, targetFile string) error {
+	const none = "None"
+
 	originalFileContent, err := os.ReadFile(targetFile)
 	if err != nil {
 		return fmt.Errorf("failed to read %s: %w", targetFile, err)
@@ -89,25 +85,25 @@ func changeCgoDirectivesForFile(targetMode string, targetFile string) error {
 	fileLines := strings.Split(string(originalFileContent), "\n")
 
 	// Initial state is "None" which does not process any lines
-	currentBlockName := "None"
+	currentBlockName := none
 	for i, line := range fileLines {
 		// process state transitions
 		// if the line starts with "// FIREWOOD_CGO_BEGIN_", set the state to the text after the prefix
 		if newBlockName, ok := strings.CutPrefix(line, "// // FIREWOOD_CGO_BEGIN_"); ok {
-			if currentBlockName != "None" {
+			if currentBlockName != none {
 				return fmt.Errorf("[ERROR] %s:%d: nested CGO blocks not allowed (found %s after %s)", targetFile, i+1, newBlockName, currentBlockName)
 			}
 			currentBlockName = newBlockName
 			continue
-		} else if line == fmt.Sprintf("// // FIREWOOD_CGO_END_%s", currentBlockName) {
-			currentBlockName = "None"
+		} else if line == "// // FIREWOOD_CGO_END_"+currentBlockName {
+			currentBlockName = none
 			continue
 		}
 
 		// If we are in a block, process the line
-		if currentBlockName != "None" {
+		if currentBlockName != none {
 			if !isCGODirective(line) {
-				return fmt.Errorf("[ERROR] %s:%d: invalid CGO directive in %s section:\n===\n%s\n===\n", targetFile, i+1, currentBlockName, line)
+				return fmt.Errorf("[ERROR] %s:%d: invalid CGO directive in %s section:\n===\n%s\n===", targetFile, i+1, currentBlockName, line)
 			}
 			if currentBlockName == targetMode {
 				fileLines[i] = activateCGOLine(fileLines[i])
@@ -117,7 +113,7 @@ func changeCgoDirectivesForFile(targetMode string, targetFile string) error {
 		}
 	}
 
-	if currentBlockName != "None" {
+	if currentBlockName != none {
 		return fmt.Errorf("[ERROR] %s: unterminated CGO block ended in %s", targetFile, currentBlockName)
 	}
 
@@ -127,6 +123,9 @@ func changeCgoDirectivesForFile(targetMode string, targetFile string) error {
 		fmt.Printf("[INFO] No changes needed to %s\n", targetFile)
 		return nil
 	}
+	// #nosec G306 - permissions are correct for source files
+	// #nosec G703 - path is safe because it is controlled by the build system
+	// and not user input
 	return os.WriteFile(targetFile, []byte(newContents), 0o644)
 }