Documentation
¶
Overview ¶
Package rewrite injects error handling into AST/DST nodes.
Package rewrite injects error handling logic by rewriting AST and DST nodes.
Index ¶
- func DecorateFile(fset *token.FileSet, file *ast.File) (*dst.File, error)
- func RenderTemplate(tmpl string, zeroExprs []ast.Expr, errName string, funcName string) ([]ast.Expr, []string, error)
- func RenderTemplateDST(tmpl string, zeroExprs []dst.Expr, errName string, funcName string) ([]dst.Expr, []string, error)
- type DstMapResult
- type Injector
- func (i *Injector) LogFallback(dstFile *dst.File, astFile *ast.File, point analysis.InjectionPoint) (bool, error)
- func (i *Injector) RewriteDefers(dstFile *dst.File, astFile *ast.File) (bool, error)
- func (i *Injector) RewriteFile(dstFile *dst.File, astFile *ast.File, points []analysis.InjectionPoint) (bool, error)
- func (i *Injector) RewritePanics(dstFile *dst.File, astFile *ast.File) (bool, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecorateFile ¶
DecorateFile converts a standard Go AST file into a DST file, preserving comments/spacing.
fset: The file set. file: The AST file to decorate.
Returns the decorated DST file.
func RenderTemplate ¶
func RenderTemplate(tmpl string, zeroExprs []ast.Expr, errName string, funcName string) ([]ast.Expr, []string, error)
RenderTemplate transforms a template into a list of AST expressions (Legacy).
tmpl: The template string (e.g. "{return-zero}, err"). zeroExprs: The zero value expressions to replace "{return-zero}". errName: The error variable name to use. funcName: The function name for logging templates.
Returns the parsed expressions, necessary imports, or an error.
func RenderTemplateDST ¶
func RenderTemplateDST(tmpl string, zeroExprs []dst.Expr, errName string, funcName string) ([]dst.Expr, []string, error)
RenderTemplateDST transforms a template into a list of DST expressions (New).
tmpl: The template string. zeroExprs: The list of zero value expressions. errName: The error variable name. funcName: The function context name.
Returns the resolved expressions, required imports, or an error.
Types ¶
type DstMapResult ¶
type DstMapResult struct {
// Node is the DST node corresponding to the input AST node.
Node dst.Node
// Parent is the parent of the resolved Node in the DST tree (or nil if Node is root).
Parent dst.Node
}
DstMapResult holds the result of a mapping operation, containing the target DST node and its immediate parent (container).
func FindDstNode ¶
func FindDstNode(fset *token.FileSet, dstFile *dst.File, astFile *ast.File, targetNode ast.Node) (DstMapResult, error)
FindDstNode locates the equivalent 'dst.Node' for a specific 'ast.Node'.
It uses the provided FileSet to compute the exact AST path enclosing the node, then traverses the 'dst.File' structure in an isomorphic manner (matching field names and list indices) to find the corresponding node in the Concrete Syntax Tree.
This is critical for translating analysis results (go/ast) into refactoring targets (dave/dst).
fset: The token.FileSet used to parse the file. dstFile: The root of the DST tree (previously decorated). astFile: The root of the AST tree (used for analysis). targetNode: The specific AST node to map (e.g. InjectionPoint.Call).
Returns a DstMapResult containing the DST node and its parent, or an error if correspondence is lost.
type Injector ¶
type Injector struct {
// Fset is the token file set.
Fset *token.FileSet
// Pkg is the package information containing type info.
Pkg *packages.Package
// ErrorTemplate is the string template for generating return statements.
ErrorTemplate string
// MainHandlerStrategy defines how to handle errors in entry points (main/init).
MainHandlerStrategy string
// NonErrorFallback defines how to handle errors when signature cannot be changed.
NonErrorFallback string
// RetainPanics indicates if panic calls should be kept in specific scenarios.
RetainPanics bool
// TestParam is the name of the testing parameter (e.g. "t") for the current injection context.
// If set, errors are handled via t.Fatal(err) instead of being returned or logged.
TestParam string
}
Injector handles the rewriting of ASTs/DSTs to inject error handling logic.
func NewInjector ¶
func NewInjector(pkg *packages.Package, errorTemplate, mainHandler string, retainPanics bool) *Injector
NewInjector creates a new Injector for the given package.
func (*Injector) LogFallback ¶
func (i *Injector) LogFallback(dstFile *dst.File, astFile *ast.File, point analysis.InjectionPoint) (bool, error)
LogFallback applies a fallback logging statement for unhandled errors.
dstFile: The DST file. astFile: The AST file. point: The specific injection point.
Returns true if changes were applied.
func (*Injector) RewriteDefers ¶
RewriteDefers scans the file for defer statements (including inside closures). It converts defers that ignore errors into a pattern using errors.Join.
If rewrite forces named returns in the function signature, it also performs normalization of return statements to "naked" returns (assignment + return) to ensure consistency and correctness with the deferred error masking.
dstFile: The DST file to rewrite. astFile: The AST file corresponding to the DST file.
Returns true if changes were applied.
func (*Injector) RewriteFile ¶
func (i *Injector) RewriteFile(dstFile *dst.File, astFile *ast.File, points []analysis.InjectionPoint) (bool, error)
RewriteFile applies specific injection points to a single file using DST transformations.
dstFile: The DST file to rewrite. astFile: The AST file corresponding to the DST file. points: The list of injection points to handle.
Returns true if any changes were applied.
func (*Injector) RewritePanics ¶
RewritePanics scans the provided DST file for explicit explicit panic calls (e.g., panic(err)) and converts them into return statements with an error.
Analysis is performed on the AST (for type safety), and transformations are applied to the DST (for comment preservation).
It performs basic reachability analysis: if replacing a panic removal exposes a fall-through path in a non-void function (i.e. missing return), it injects a terminal return statement.
If RetainPanics is enabled, it skips panics that do not appear to wrap errors (e.g. string assertions).
dstFile: The DST file to modify. astFile: The AST file corresponding to the DST file (used for type analysis).
Returns true if any changes were applied.