runner

Documentation

Overview

Package runner orchestrates analysis, refactoring, and formatting passes.

Package runner orchestrates analysis, refactoring, and persistence.

Index

• func PatchSignature(info *types.Info, decl *ast.FuncDecl, pkg *types.Package) error
• func Run(opts Options) error
• type FuncContext
  • func FindEnclosingFunc(pkg *packages.Package, file *ast.File, pos token.Pos) *FuncContext
  • func (fc *FuncContext) IsLiteral() bool
• type Options

Functions

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). This allows subsequent analysis passes (like the Injector) to see the correct return types without requiring a generic packages.Load reload (which is slow).

It performs the following: 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.Uses to point all existing references to the new object.

info: The package type info. decl: The modified AST declaration (should already have the 'error' field in AST). pkg: The types.Package the function belongs to.

func Run

func Run(opts Options) error

Run executes analysis and rewrites based on the provided options.

opts: The configuration options.

Returns failure if analysis or rewriting fails.

Types

type FuncContext

type FuncContext struct {
	// Sig is the type signature of the function, resolved from type information.
	Sig *types.Signature
	// Decl is set if the enclosing function is a named declaration (e.g. func Foo() {}).
	Decl *ast.FuncDecl
	// Lit is set if the enclosing function is a literal (e.g. func() {}).
	Lit *ast.FuncLit
	// Node is the AST node corresponding to the function (either Decl or Lit).
	Node ast.Node
	// TestParam is the name of the *testing.T (or B/F) parameter if this function is a test handler.
	// This is populated for top-level Test functions AND subtest closures (t.Run).
	TestParam string
}

FuncContext represents the function (Declaration or Literal) enclosing a specific point in code. It provides access to the semantic signature and the syntactic AST node required for refactoring.

func FindEnclosingFunc

func FindEnclosingFunc(pkg *packages.Package, file *ast.File, pos token.Pos) *FuncContext

FindEnclosingFunc resolves the nearest function wrapping the provided position in the file. It traverses the AST upwards from the position to find either a FuncDecl or a FuncLit. It checks for testing contexts (Test functions or t.Run closures) to ensure correct error handling.

pkg: The package containing the file, populated with syntax and type info. file: The AST file associated with the position. pos: The token position to start the search from.

Returns nil if no function context encloses the position or if type information is missing.

func (*FuncContext) IsLiteral

func (fc *FuncContext) IsLiteral() bool

IsLiteral reports whether the function context is an anonymous function literal.

type Options

type Options struct {
	// EnablePreexistingErr enables fixes for functions that already return an error.
	EnablePreexistingErr bool

	// EnableNonExistingErr enables changing function signatures to add error returns.
	EnableNonExistingErr bool

	// EnableThirdPartyErr enables checking errors from third-party libraries.
	EnableThirdPartyErr bool

	// EnableTestRefactor allows modification of test function bodies.
	EnableTestRefactor bool

	// Check enables CI mode (exit 1 on issues).
	Check bool

	// ExcludeGlob is a list of file glob patterns to exclude.
	ExcludeGlob []string

	// ExcludeSymbolGlob is a list of symbol glob patterns to exclude.
	ExcludeSymbolGlob []string

	// DryRun enables preview mode.
	DryRun bool

	// UseDefaultExclusions applies the default list of ignored symbols.
	UseDefaultExclusions bool

	// PanicToReturn enables rewriting of explicit panic() calls.
	PanicToReturn bool

	// RetainPanics restricts panic replacement to only those wrapping errors.
	RetainPanics bool

	// Recursive enables recursive directory scanning.
	Recursive bool

	// Paths to analyze.
	Paths []string

	// MainHandler strategy for entry points.
	MainHandler string

	// NonErrorFallback strategy for functions that do not return error.
	NonErrorFallback string

	// ErrorTemplate template for return statements.
	ErrorTemplate string

	// Reporter collects statistics.
	Reporter *report.Reporter
}

Options configuration for the runner.