refactor

Documentation

Overview

Package refactor provides type-aware refactoring helpers for propagating errors and updating function signatures.

Package refactor updates signatures and call sites to propagate errors.

Index

• func AddErrorToFuncTypeDST(ft *dst.FuncType) (bool, error)
• func AddErrorToSignature(fset *token.FileSet, decl *ast.FuncDecl) (bool, error)
• func AddErrorToSignatureDST(decl *dst.FuncDecl) (bool, error)
• func EnsureNamedReturns(fset *token.FileSet, decl *ast.FuncDecl, info *types.Info) (bool, error)
• func EnsureNamedReturnsDST(decl *dst.FuncDecl) (bool, error)
• func ExtendSignatureWithError(oldSig *types.Signature, pkg *types.Package) *types.Signature
• func HandleEntryPoint(pkg *packages.Package, dstFile *dst.File, call *ast.CallExpr, stmt ast.Stmt, ...) error
• func HandleTestError(pkg *packages.Package, dstFile *dst.File, call *ast.CallExpr, stmt ast.Stmt, ...) error
• func IsEntryPoint(fn *types.Func) bool
• func NameForExpr(expr ast.Expr) string
• func NameForType(t types.Type) string
• func PatchSignature(info *types.Info, decl *ast.FuncDecl, pkg *types.Package) error
• func PatchVarType(info *types.Info, ident *ast.Ident, newSig *types.Signature) (*types.Var, error)
• func PropagateCallers(pkgs []*packages.Package, provider DstProvider, initialTarget types.Object, ...) (int, error)
• type DstProvider
• type MainHandlerStrategy

Functions

func AddErrorToFuncTypeDST

func AddErrorToFuncTypeDST(ft *dst.FuncType) (bool, error)

AddErrorToFuncTypeDST modifies a standalone DST function type signature.

ft: The function type to modify.

Returns true if modified.

func AddErrorToSignature

func AddErrorToSignature(fset *token.FileSet, decl *ast.FuncDecl) (bool, error)

AddErrorToSignature modifies a function declaration signature to include an error return type.

fset: The file set associated with the declaration. decl: The function declaration to modify.

Returns true if the signature was changed.

func AddErrorToSignatureDST

func AddErrorToSignatureDST(decl *dst.FuncDecl) (bool, error)

AddErrorToSignatureDST modifies a DST function declaration signature to include an error return type.

decl: The DST function declaration to modify.

Returns true if the signature was changed.

func EnsureNamedReturns

func EnsureNamedReturns(fset *token.FileSet, decl *ast.FuncDecl, info *types.Info) (bool, error)

EnsureNamedReturns checks AST function declarations for unnamed return values and names them.

fset: The file set. decl: The function declaration. info: The type info (optional, used for improved naming).

Returns true if changes were made.

func EnsureNamedReturnsDST

func EnsureNamedReturnsDST(decl *dst.FuncDecl) (bool, error)

EnsureNamedReturnsDST checks DST function declarations for unnamed return values and names them.

decl: The DST function declaration.

Returns true if changes were made.

func ExtendSignatureWithError

func ExtendSignatureWithError(oldSig *types.Signature, pkg *types.Package) *types.Signature

ExtendSignatureWithError creates a new signature based on oldSig with an added 'error' return value.

oldSig: The original signature. pkg: The package context.

Returns a new signature with extracted parameters and results, plus a trailing error return.

func HandleEntryPoint

func HandleEntryPoint(pkg *packages.Package, dstFile *dst.File, call *ast.CallExpr, stmt ast.Stmt, strategy string) error

HandleEntryPoint handles errors in entry points like main() or init(). It injects a terminal handler (log.Fatal/panic/os.Exit) instead of returning the error.

pkg: The package info. dstFile: The DST file. call: The AST call expression (used to locate the call DST node via mapping). stmt: The AST statement enclosing the call. strategy: The terminal handling strategy ("log-fatal", "panic", "os-exit").

func HandleTestError

func HandleTestError(pkg *packages.Package, dstFile *dst.File, call *ast.CallExpr, stmt ast.Stmt, testParamName string) error

HandleTestError handles errors within testing functions (TestXxx). It injects `t.Fatal(err)` calls.

pkg: The package info. dstFile: The DST file. call: The AST call expression. stmt: The AST statement enclosing the call. testParamName: The name of the testing parameter (e.g., "t", "b").

func IsEntryPoint

func IsEntryPoint(fn *types.Func) bool

IsEntryPoint checks if the function is main() or init().

func NameForExpr

func NameForExpr(expr ast.Expr) string

NameForExpr generates a name based purely on the AST expression. This is a fallback when TypeInfo is missing (e.g. in some unit tests).

expr: The AST expression (e.g. &ast.Ident{Name: "int"})

func NameForType

func NameForType(t types.Type) string

NameForType generates a heuristic variable name for a given Go type. It handles standard library idioms (Context -> ctx), pointer stripping, and basic camelCase conversion for named types.

t: The type to analyze.

Returns a short, idiomatic variable name (e.g., "ctx", "s", "user").

func PatchSignature

func PatchSignature(info *types.Info, decl *ast.FuncDecl, pkg *types.Package) error

PatchSignature manually updates the types.Info maps to reflect a change in a function's signature (specifically adding an error return). Please ensure the AST is modified before calling this.

actions: 1. Retrieves the existing function object. 2. Constructs a new types.Signature with the appended 'error' return value. 3. Creates a new types.Func object pointing to this signature. 4. Updates info.Defs to point to the new object. 5. Updates info.Types map for the function type node. 6. Updates info.Uses to point all existing references to the new object.

info: The type info map to update. decl: The modified function declaration AST node (must already have 'error' in results). pkg: The package the function belongs to.

func PatchVarType

func PatchVarType(info *types.Info, ident *ast.Ident, newSig *types.Signature) (*types.Var, error)

PatchVarType manually updates the types.Info maps to reflect a change in a variable's type. It constructs a new types.Var object with the updated signature and replaces references.

info: The type info map to update. ident: The identifier node of the variable. newSig: The new signature to apply to the variable.

Returns the new variable object.

func PropagateCallers

func PropagateCallers(pkgs []*packages.Package, provider DstProvider, initialTarget types.Object, strategy string) (int, error)

PropagateCallers updates all call sites (and value assignments) of a modified object.

pkgs: The list of loaded packages to search for usages. provider: The provider for retrieving DST files. initialTarget: The object (function or variable) whose signature changed. strategy: The strategy to use for terminal functions (e.g. main) if encountered.

Returns the number of call sites updated.

Types

type DstProvider

type DstProvider interface {
	// Get retrieves the DST file corresponding to the given AST file.
	// pkg: The package containing the file.
	// file: The AST file map key.
	Get(pkg *packages.Package, file *ast.File) (*dst.File, error)

	// MarkModified marks a file as modified to ensure it is saved back to disk.
	// file: The AST file associated with the modified DST.
	MarkModified(file *ast.File)
}

DstProvider abstracts the management of DST files.

type MainHandlerStrategy

type MainHandlerStrategy string

MainHandlerStrategy defines how errors should be handled in entry points like main or init.

const (
	// HandlerLogFatal uses log.Fatal(err).
	HandlerLogFatal MainHandlerStrategy = "log-fatal"
	// HandlerOsExit uses fmt.Println(err) followed by os.Exit(1).
	HandlerOsExit MainHandlerStrategy = "os-exit"
	// HandlerPanic uses panic(err).
	HandlerPanic MainHandlerStrategy = "panic"
)