go/analysis/passes/gofix: go:fix directive checker

Add an analyzer that checks the validity of go:fix directives.

To avoid pulling the inlining framework into go vet, we split the gofix
analyzers into three packages.

The internal/gofix/findgofix package finds each `go:fix inline`
directive, checks it for errors, and invokes a callback.

The internal/gofix package uses findgofix with callbacks that
register facts, and then does the inlining.

The go/analysis/passes/gofix package uses findgofix to find errors,
but takes no other action.

vet_std_test passes, indicating that there were no findings in the
standard library.

A followup CL on the go repo will vendor x/tools at head and
add this analyzer to go vet.

Change-Id: Ib9ebe38cc719d7b3d85beccd76a9bedf8a2cd077
Reviewed-on: https://go-review.googlesource.com/c/tools/+/664176
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Alan Donovan <adonovan@google.com>

Author: jba

go/analysis/passes/gofix/doc.go

@@ -0,0 +1,49 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package gofix defines an Analyzer that checks "//go:fix inline" directives.
+See golang.org/x/tools/internal/gofix/doc.go for details.
+
+# Analyzer gofixdirective
+
+gofixdirective: validate uses of gofix comment directives
+
+The gofixdirective analyzer checks "//go:fix inline" directives for correctness.
+
+The proposal https://go.dev/issue/32816 introduces the "//go:fix" directives.
+
+The analyzer checks for the following issues:
+
+- A constant definition can be marked for inlining only if it refers to another
+named constant.
+
+	//go:fix inline
+	const (
+		a = 1       // error
+		b = iota    // error
+		c = math.Pi // OK
+	)
+
+- A type definition can be marked for inlining only if it is an alias.
+
+	//go:fix inline
+	type (
+		T int    // error
+		A = int  // OK
+	)
+
+- An alias whose right-hand side contains a non-literal array size
+cannot be marked for inlining.
+
+	const two = 2
+
+	//go:fix inline
+	type (
+		A = []int     // OK
+		B = [1]int    // OK
+		C = [two]int  // error
+	)
+*/
+package gofix

go/analysis/passes/gofix/gofix.go

@@ -0,0 +1,34 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package gofix defines an analyzer that checks go:fix directives.
+package gofix
+
+import (
+	_ "embed"
+
+	"golang.org/x/tools/go/analysis"
+	"golang.org/x/tools/go/analysis/passes/inspect"
+	"golang.org/x/tools/go/ast/inspector"
+	"golang.org/x/tools/internal/analysisinternal"
+	"golang.org/x/tools/internal/astutil/cursor"
+	"golang.org/x/tools/internal/gofix/findgofix"
+)
+
+//go:embed doc.go
+var doc string
+
+var Analyzer = &analysis.Analyzer{
+	Name:     "gofixdirective",
+	Doc:      analysisinternal.MustExtractDoc(doc, "gofixdirective"),
+	URL:      "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/gofix",
+	Run:      run,
+	Requires: []*analysis.Analyzer{inspect.Analyzer},
+}
+
+func run(pass *analysis.Pass) (any, error) {
+	root := cursor.Root(pass.ResultOf[inspect.Analyzer].(*inspector.Inspector))
+	findgofix.Find(pass, root, nil)
+	return nil, nil
+}

go/analysis/passes/gofix/gofix_test.go

@@ -0,0 +1,17 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package gofix_test
+
+import (
+	"testing"
+
+	"golang.org/x/tools/go/analysis/analysistest"
+	"golang.org/x/tools/go/analysis/passes/gofix"
+)
+
+func Test(t *testing.T) {
+	testdata := analysistest.TestData()
+	analysistest.Run(t, testdata, gofix.Analyzer, "a")
+}

go/analysis/passes/gofix/testdata/src/a/a.go

@@ -0,0 +1,47 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains tests for the gofix checker.
+
+package a
+
+const one = 1
+
+//go:fix inline
+const (
+	in3  = one
+	in4  = one
+	bad1 = 1 // want `invalid //go:fix inline directive: const value is not the name of another constant`
+)
+
+//go:fix inline
+const in5,
+	in6,
+	bad2 = one, one,
+	one + 1 // want `invalid //go:fix inline directive: const value is not the name of another constant`
+
+//go:fix inline
+const (
+	a = iota // want `invalid //go:fix inline directive: const value is iota`
+	b
+	in7 = one
+)
+
+func shadow() {
+	//go:fix inline
+	const a = iota // want `invalid //go:fix inline directive: const value is iota`
+
+	const iota = 2
+
+	//go:fix inline
+	const b = iota // not an error: iota is not the builtin
+}
+
+// Type aliases
+
+//go:fix inline
+type A int // want `invalid //go:fix inline directive: not a type alias`
+
+//go:fix inline
+type E = map[[one]string][]int // want `invalid //go:fix inline directive: array types not supported`

go/analysis/unitchecker/vet_std_test.go

@@ -24,6 +24,7 @@ import (
 	"golang.org/x/tools/go/analysis/passes/directive"
 	"golang.org/x/tools/go/analysis/passes/errorsas"
 	"golang.org/x/tools/go/analysis/passes/framepointer"
+	"golang.org/x/tools/go/analysis/passes/gofix"
 	"golang.org/x/tools/go/analysis/passes/httpresponse"
 	"golang.org/x/tools/go/analysis/passes/ifaceassert"
 	"golang.org/x/tools/go/analysis/passes/loopclosure"
@@ -62,6 +63,7 @@ func vet() {
 		directive.Analyzer,
 		errorsas.Analyzer,
 		framepointer.Analyzer,
+		gofix.Analyzer,
 		httpresponse.Analyzer,
 		ifaceassert.Analyzer,
 		loopclosure.Analyzer,

internal/gofix/doc.go

@@ -6,7 +6,6 @@
 Package gofix defines an Analyzer that inlines calls to functions
 and uses of constants
 marked with a "//go:fix inline" directive.
-A second analyzer only checks uses of the directive.
 
 # Analyzer gofix
 

internal/gofix/findgofix/findgofix.go

@@ -0,0 +1,143 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package findgofix searches for and validates go:fix directives. The
+// internal/gofix package uses findgofix to perform inlining.
+// The go/analysis/passes/gofix package uses findgofix to check for problems
+// with go:fix directives.
+//
+// findgofix is separate from gofix to avoid depending on refactor/inline,
+// which is large.
+package findgofix
+
+// This package is tested by internal/gofix.
+
+import (
+	"go/ast"
+	"go/token"
+	"go/types"
+
+	"golang.org/x/tools/go/analysis"
+	internalastutil "golang.org/x/tools/internal/astutil"
+	"golang.org/x/tools/internal/astutil/cursor"
+)
+
+// A Handler handles language entities with go:fix directives.
+type Handler interface {
+	HandleFunc(*ast.FuncDecl)
+	HandleAlias(*ast.TypeSpec)
+	HandleConst(name, rhs *ast.Ident)
+}
+
+// Find finds functions and constants annotated with an appropriate "//go:fix"
+// comment (the syntax proposed by #32816), and calls handler methods for each one.
+// h may be nil.
+func Find(pass *analysis.Pass, root cursor.Cursor, h Handler) {
+	for cur := range root.Preorder((*ast.FuncDecl)(nil), (*ast.GenDecl)(nil)) {
+		switch decl := cur.Node().(type) {
+		case *ast.FuncDecl:
+			findFunc(decl, h)
+
+		case *ast.GenDecl:
+			if decl.Tok != token.CONST && decl.Tok != token.TYPE {
+				continue
+			}
+			declInline := hasFixInline(decl.Doc)
+			// Accept inline directives on the entire decl as well as individual specs.
+			for _, spec := range decl.Specs {
+				switch spec := spec.(type) {
+				case *ast.TypeSpec: // Tok == TYPE
+					findAlias(pass, spec, declInline, h)
+
+				case *ast.ValueSpec: // Tok == CONST
+					findConst(pass, spec, declInline, h)
+				}
+			}
+		}
+	}
+}
+
+func findFunc(decl *ast.FuncDecl, h Handler) {
+	if !hasFixInline(decl.Doc) {
+		return
+	}
+	if h != nil {
+		h.HandleFunc(decl)
+	}
+}
+
+func findAlias(pass *analysis.Pass, spec *ast.TypeSpec, declInline bool, h Handler) {
+	if !declInline && !hasFixInline(spec.Doc) {
+		return
+	}
+	if !spec.Assign.IsValid() {
+		pass.Reportf(spec.Pos(), "invalid //go:fix inline directive: not a type alias")
+		return
+	}
+
+	// Disallow inlines of type expressions containing array types.
+	// Given an array type like [N]int where N is a named constant, go/types provides
+	// only the value of the constant as an int64. So inlining A in this code:
+	//
+	//    const N = 5
+	//    type A = [N]int
+	//
+	// would result in [5]int, breaking the connection with N.
+	for n := range ast.Preorder(spec.Type) {
+		if ar, ok := n.(*ast.ArrayType); ok && ar.Len != nil {
+			// Make an exception when the array length is a literal int.
+			if lit, ok := ast.Unparen(ar.Len).(*ast.BasicLit); ok && lit.Kind == token.INT {
+				continue
+			}
+			pass.Reportf(spec.Pos(), "invalid //go:fix inline directive: array types not supported")
+			return
+		}
+	}
+	if h != nil {
+		h.HandleAlias(spec)
+	}
+}
+
+func findConst(pass *analysis.Pass, spec *ast.ValueSpec, declInline bool, h Handler) {
+	specInline := hasFixInline(spec.Doc)
+	if declInline || specInline {
+		for i, nameIdent := range spec.Names {
+			if i >= len(spec.Values) {
+				// Possible following an iota.
+				break
+			}
+			var rhsIdent *ast.Ident
+			switch val := spec.Values[i].(type) {
+			case *ast.Ident:
+				// Constants defined with the predeclared iota cannot be inlined.
+				if pass.TypesInfo.Uses[val] == builtinIota {
+					pass.Reportf(val.Pos(), "invalid //go:fix inline directive: const value is iota")
+					return
+				}
+				rhsIdent = val
+			case *ast.SelectorExpr:
+				rhsIdent = val.Sel
+			default:
+				pass.Reportf(val.Pos(), "invalid //go:fix inline directive: const value is not the name of another constant")
+				return
+			}
+			if h != nil {
+				h.HandleConst(nameIdent, rhsIdent)
+			}
+		}
+	}
+}
+
+// hasFixInline reports the presence of a "//go:fix inline" directive
+// in the comments.
+func hasFixInline(cg *ast.CommentGroup) bool {
+	for _, d := range internalastutil.Directives(cg) {
+		if d.Tool == "go" && d.Name == "fix" && d.Args == "inline" {
+			return true
+		}
+	}
+	return false
+}
+
+var builtinIota = types.Universe.Lookup("iota")