refactor: consolidate shared linter AST helpers

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
pelikhan · Jun 9, 2026 · Jun 9, 2026 · Jun 9, 2026 · Jun 9, 2026 · Jun 9, 2026
commit a477f0d6a4287dbe4efbdee061dca7c202c8c81b
diff --git a/pkg/linters/errormessage/errormessage.go b/pkg/linters/errormessage/errormessage.go
@@ -14,6 +14,7 @@ import (
 	"golang.org/x/tools/go/analysis/passes/inspect"
 	"golang.org/x/tools/go/ast/inspector"
 
+	"github.com/github/gh-aw/pkg/linters/internal/astutil"
 	"github.com/github/gh-aw/pkg/linters/internal/filecheck"
 	"github.com/github/gh-aw/pkg/linters/internal/nolint"
 )
@@ -118,18 +119,6 @@ func extractLiteralErrorMessage(call *ast.CallExpr) (string, bool) {
 	return unquoted, true
 }
 
-func isFmtErrorf(call *ast.CallExpr) bool {
-	sel, ok := call.Fun.(*ast.SelectorExpr)
-	if !ok {
-		return false
-	}
-	ident, ok := sel.X.(*ast.Ident)
-	if !ok {
-		return false
-	}
-	return ident.Name == "fmt" && sel.Sel.Name == "Errorf"
-}
-
 func isNewValidationErrorCall(call *ast.CallExpr) bool {
 	switch fun := call.Fun.(type) {
 	case *ast.Ident:
@@ -142,7 +131,7 @@ func isNewValidationErrorCall(call *ast.CallExpr) bool {
 }
 
 func checkValidationFmtErrorf(pass *analysis.Pass, call *ast.CallExpr, filename string) {
-	if !strings.HasSuffix(filename, "_validation.go") || !isFmtErrorf(call) {
+	if !strings.HasSuffix(filename, "_validation.go") || !astutil.IsFmtErrorf(pass, call) {
 		return
 	}
 	pass.ReportRangef(call, "use NewValidationError(...) instead of fmt.Errorf(...) in validation files")
@@ -182,7 +171,7 @@ func checkNewValidationSuggestion(pass *analysis.Pass, call *ast.CallExpr) {
 }
 
 func checkFailedToErrorfWrap(pass *analysis.Pass, call *ast.CallExpr, msg string) {
-	if !isFmtErrorf(call) {
+	if !astutil.IsFmtErrorf(pass, call) {
 		return
 	}
 	if strings.HasPrefix(strings.ToLower(msg), "failed to ") && strings.Contains(msg, ": %w") {

diff --git a/pkg/linters/errormessage/testdata/src/errormessage/validation_target_validation.go b/pkg/linters/errormessage/testdata/src/errormessage/validation_target_validation.go
@@ -1,7 +1,10 @@
 package errormessage
 
-import "fmt"
-import "errors"
+import (
+	"errors"
+	"fmt"
+	fmtalias "fmt"
+)
 
 func NewValidationError(field, value, reason, suggestion string) error {
 	return errors.New(reason)
@@ -22,3 +25,16 @@ func badValidationErrorObject() error {
 func badValidationSuggestionNoExample() error {
 	return NewValidationError("tools.github", "remote", "unsupported", "Set mode to local") // want `NewValidationError\(\.\.\.\) suggestion should include an example \(for example: YAML snippet\)`
 }
+
+func badValidationFormatAliased() error {
+	return fmtalias.Errorf("invalid value") // want `use NewValidationError\(\.\.\.\) instead of fmt\.Errorf\(\.\.\.\) in validation files` `error message uses negative language without constructive guidance; include expected/requires/should/example details`
+}
+
+type formatter struct{}
+
+func (formatter) Errorf(msg string, _ ...any) error { return errors.New(msg) }
+
+func localShadowNotFmtPackage() error {
+	fmt := formatter{}
+	return fmt.Errorf("all good")
+}
diff --git a/pkg/linters/errstringmatch/errstringmatch.go b/pkg/linters/errstringmatch/errstringmatch.go
@@ -6,13 +6,13 @@ package errstringmatch
 import (
 	"fmt"
 	"go/ast"
-	"go/token"
 	"go/types"
 
 	"golang.org/x/tools/go/analysis"
 	"golang.org/x/tools/go/analysis/passes/inspect"
 	"golang.org/x/tools/go/ast/inspector"
 
+	"github.com/github/gh-aw/pkg/linters/internal/astutil"
 	"github.com/github/gh-aw/pkg/linters/internal/filecheck"
 	"github.com/github/gh-aw/pkg/linters/internal/nolint"
 )
@@ -114,8 +114,7 @@ func isErrDotError(pass *analysis.Pass, expr ast.Expr) bool {
 
 // isStringLiteral returns true when expr is a string literal or untyped string constant.
 func isStringLiteral(pass *analysis.Pass, expr ast.Expr) bool {
-	lit, ok := expr.(*ast.BasicLit)
-	if ok && lit.Kind == token.STRING {
+	if astutil.IsStringLiteral(expr) {
 		return true
 	}
 	// Also accept typed/untyped string constants (e.g. a const identifier).

diff --git a/pkg/linters/fmterrorfnoverbs/fmterrorfnoverbs.go b/pkg/linters/fmterrorfnoverbs/fmterrorfnoverbs.go
@@ -7,13 +7,13 @@ import (
 	"fmt"
 	"go/ast"
 	"go/token"
-	"go/types"
 	"strings"
 
 	"golang.org/x/tools/go/analysis"
 	"golang.org/x/tools/go/analysis/passes/inspect"
 	"golang.org/x/tools/go/ast/inspector"
 
+	"github.com/github/gh-aw/pkg/linters/internal/astutil"
 	"github.com/github/gh-aw/pkg/linters/internal/nolint"
 )
 
@@ -43,7 +43,7 @@ func run(pass *analysis.Pass) (any, error) {
 			return
 		}
 
-		if !isFmtErrorf(pass, call) {
+		if !astutil.IsFmtErrorf(pass, call) {
 			return
 		}
 
@@ -73,27 +73,3 @@ func run(pass *analysis.Pass) (any, error) {
 
 	return nil, nil
 }
-
-// isFmtErrorf returns true if the call expression is a call to fmt.Errorf.
-func isFmtErrorf(pass *analysis.Pass, call *ast.CallExpr) bool {
-	sel, ok := call.Fun.(*ast.SelectorExpr)
-	if !ok {
-		return false
-	}
-	if sel.Sel.Name != "Errorf" {
-		return false
-	}
-	pkgIdent, ok := sel.X.(*ast.Ident)
-	if !ok {
-		return false
-	}
-	obj := pass.TypesInfo.ObjectOf(pkgIdent)
-	if obj == nil {
-		return false
-	}
-	pkgName, ok := obj.(*types.PkgName)
-	if !ok {
-		return false
-	}
-	return pkgName.Imported().Path() == "fmt"
-}
diff --git a/pkg/linters/fmterrorfnoverbs/testdata/src/fmterrorfnoverbs/fmterrorfnoverbs.go b/pkg/linters/fmterrorfnoverbs/testdata/src/fmterrorfnoverbs/fmterrorfnoverbs.go
@@ -4,6 +4,7 @@ package fmterrorfnoverbs
 import (
 	"errors"
 	"fmt"
+	fmtalias "fmt"
 )
 
 func bad() error {
@@ -34,3 +35,16 @@ func suppressedPreviousLine() error {
 func suppressedSameLine() error {
 	return fmt.Errorf("this is intentionally static") //nolint:fmterrorfnoverbs
 }
+
+func badAliasedImport() error {
+	return fmtalias.Errorf("alias import static message") // want `fmt\.Errorf called with no format verbs; use errors\.New`
+}
+
+type shadowFormatter struct{}
+
+func (shadowFormatter) Errorf(msg string, _ ...any) error { return errors.New(msg) }
+
+func localShadowNotFlagged() error {
+	fmt := shadowFormatter{}
+	return fmt.Errorf("not fmt package")
+}
diff --git a/pkg/linters/internal/astutil/astutil.go b/pkg/linters/internal/astutil/astutil.go
@@ -0,0 +1,67 @@
+// Package astutil provides shared AST/type helper functions used by linters.
+package astutil
+
+import (
+	"go/ast"
+	"go/token"
+	"go/types"
+
+	"golang.org/x/tools/go/analysis"
+)
+
+// IsLocalObject reports whether obj is a local (non-package-scope) object.
+func IsLocalObject(obj types.Object) bool {
+	if obj == nil {
+		return false
+	}
+	parent := obj.Parent()
+	if parent == nil {
+		return false
+	}
+	pkg := obj.Pkg()
+	return pkg == nil || parent != pkg.Scope()
+}
+
+// RhsExprForIndex returns the RHS expression mapped to idx when available.
+func RhsExprForIndex(rhs []ast.Expr, idx int) (ast.Expr, bool) {
+	switch {
+	case len(rhs) == 0:
+		return nil, false
+	case len(rhs) == 1 && idx == 0:
+		return rhs[0], true
+	case idx < len(rhs):
+		return rhs[idx], true
+	default:
+		return nil, false
+	}
+}
+
+// IsStringLiteral reports whether expr is a string literal.
+func IsStringLiteral(expr ast.Expr) bool {
+	lit, ok := expr.(*ast.BasicLit)
+	return ok && lit.Kind == token.STRING
+}
+
+// IsFmtErrorf reports whether call is a call to fmt.Errorf (including aliases).
+func IsFmtErrorf(pass *analysis.Pass, call *ast.CallExpr) bool {
+	sel, ok := call.Fun.(*ast.SelectorExpr)
+	if !ok {
+		return false
+	}
+	if sel.Sel.Name != "Errorf" {
+		return false
+	}
+	pkgIdent, ok := sel.X.(*ast.Ident)
+	if !ok {
+		return false
+	}
+	obj := pass.TypesInfo.ObjectOf(pkgIdent)
+	if obj == nil {
+		return false
+	}
+	pkgName, ok := obj.(*types.PkgName)
+	if !ok {
+		return false
+	}
+	return pkgName.Imported().Path() == "fmt"
+}
diff --git a/pkg/linters/lenstringzero/lenstringzero.go b/pkg/linters/lenstringzero/lenstringzero.go
@@ -12,6 +12,7 @@ import (
 	"golang.org/x/tools/go/analysis/passes/inspect"
 	"golang.org/x/tools/go/ast/inspector"
 
+	"github.com/github/gh-aw/pkg/linters/internal/astutil"
 	"github.com/github/gh-aw/pkg/linters/internal/filecheck"
 )
 
@@ -142,7 +143,7 @@ func collectLenStringAliasesFromAssignStmt(pass *analysis.Pass, stmt *ast.Assign
 			continue
 		}
 		obj := pass.TypesInfo.ObjectOf(ident)
-		if obj == nil || !isLocalObject(obj) {
+		if obj == nil || !astutil.IsLocalObject(obj) {
 			continue
 		}
 
@@ -152,7 +153,7 @@ func collectLenStringAliasesFromAssignStmt(pass *analysis.Pass, stmt *ast.Assign
 				delete(aliases, obj)
 				continue
 			}
-			rhs, ok := rhsExprForIndex(stmt.Rhs, i)
+			rhs, ok := astutil.RhsExprForIndex(stmt.Rhs, i)
 			if !ok {
 				delete(aliases, obj)
 				continue
@@ -174,10 +175,10 @@ func collectLenStringAliasesFromValueSpec(pass *analysis.Pass, spec *ast.ValueSp
 			continue
 		}
 		obj := pass.TypesInfo.ObjectOf(name)
-		if obj == nil || !isLocalObject(obj) {
+		if obj == nil || !astutil.IsLocalObject(obj) {
 			continue
 		}
-		rhs, ok := rhsExprForIndex(spec.Values, i)
+		rhs, ok := astutil.RhsExprForIndex(spec.Values, i)
 		if !ok {
 			delete(aliases, obj)
 			continue
@@ -222,33 +223,10 @@ func lenStringArg(pass *analysis.Pass, expr ast.Expr) (ast.Expr, bool) {
 	return arg, true
 }
 
-func rhsExprForIndex(rhs []ast.Expr, idx int) (ast.Expr, bool) {
-	switch {
-	case len(rhs) == 0:
-		return nil, false
-	case idx < len(rhs):
-		return rhs[idx], true
-	default:
-		return nil, false
-	}
-}
-
 func deleteLenStringAliasForExpr(pass *analysis.Pass, aliases map[types.Object]ast.Expr, expr ast.Expr) {
 	ident, ok := expr.(*ast.Ident)
 	if !ok {
 		return
 	}
 	delete(aliases, pass.TypesInfo.ObjectOf(ident))
 }
-
-func isLocalObject(obj types.Object) bool {
-	if obj == nil {
-		return false
-	}
-	parent := obj.Parent()
-	if parent == nil {
-		return false
-	}
-	pkg := obj.Pkg()
-	return pkg == nil || parent != pkg.Scope()
-}