Documentation
¶
Overview ¶
Package driverutil defines implementation helper functions for analysis drivers such as unitchecker, {single,multi}checker, and analysistest.
Index ¶
- func ApplyFixes(actions []FixAction, printDiff, verbose bool) error
- func CheckReadable(pass *analysis.Pass, filename string) error
- func FormatSourceRemoveImports(pkg *types.Package, src []byte) ([]byte, error)
- func PrintPlain(out io.Writer, fset *token.FileSet, contextLines int, diag analysis.Diagnostic)
- func ResolveURL(a *analysis.Analyzer, d analysis.Diagnostic) (string, error)
- func ValidateFixes(fset *token.FileSet, a *analysis.Analyzer, fixes []analysis.SuggestedFix) error
- type FixAction
- type JSONDiagnostic
- type JSONRelatedInformation
- type JSONSuggestedFix
- type JSONTextEdit
- type JSONTree
- type ReadFileFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyFixes ¶
ApplyFixes attempts to apply the first suggested fix associated with each diagnostic reported by the specified actions. All fixes must have been validated by ValidateFixes.
Each fix is treated as an independent change; fixes are merged in an arbitrary deterministic order as if by a three-way diff tool such as the UNIX diff3 command or 'git merge'. Any fix that cannot be cleanly merged is discarded, in which case the final summary tells the user to re-run the tool. TODO(adonovan): make the checker tool re-run the analysis itself.
When the same file is analyzed as a member of both a primary package "p" and a test-augmented package "p [p.test]", there may be duplicate diagnostics and fixes. One set of fixes will be applied and the other will be discarded; but re-running the tool may then show zero fixes, which may cause the confused user to wonder what happened to the other ones. TODO(adonovan): consider pre-filtering completely identical fixes.
A common reason for overlapping fixes is duplicate additions of the same import. The merge algorithm may often cleanly resolve such fixes, coalescing identical edits, but the merge may sometimes be confused by nearby changes.
Even when merging succeeds, there is no guarantee that the composition of the two fixes is semantically correct. Coalescing identical edits is appropriate for imports, but not for, say, increments to a counter variable; the correct resolution in that case might be to increment it twice.
Or consider two fixes that each delete the penultimate reference to a local variable: each fix is sound individually, and they may be textually distant from each other, but when both are applied, the program is no longer valid because it has an unreferenced local variable. (ApplyFixes solves the analogous problem for imports by eliminating imports whose name is unreferenced in the remainder of the fixed file.)
Merging depends on both the order of fixes and they order of edits within them. For example, if three fixes add import "a" twice and import "b" once, the two imports of "a" may be combined if they appear in order [a, a, b], or not if they appear as [a, b, a]. TODO(adonovan): investigate an algebraic approach to imports; that is, for fixes to Go source files, convert changes within the import(...) portion of the file into semantic edits, compose those edits algebraically, then convert the result back to edits.
applyFixes returns success if all fixes are valid, could be cleanly merged, and the corresponding files were successfully updated.
If printDiff (from the -diff flag) is set, instead of updating the files it display the final patch composed of all the cleanly merged fixes.
TODO(adonovan): handle file-system level aliases such as symbolic links using robustio.FileID.
func CheckReadable ¶
CheckReadable enforces the access policy defined by the ReadFile field of analysis.Pass.
func FormatSourceRemoveImports ¶
FormatSourceRemoveImports is a variant of [format.Source] that removes imports that became redundant when fixes were applied.
Import removal is necessarily heuristic since we do not have type information for the fixed file and thus cannot accurately tell whether k is among the free names of T{k: 0}, which requires knowledge of whether T is a struct type.
func PrintPlain ¶
PrintPlain prints a diagnostic in plain text form. If contextLines is nonnegative, it also prints the offending line plus this many lines of context.
func ResolveURL ¶
ResolveURL resolves the URL field for a Diagnostic from an Analyzer and returns the URL. See Diagnostic.URL for details.
func ValidateFixes ¶
ValidateFixes validates the set of fixes for a single diagnostic. Any error indicates a bug in the originating analyzer.
It updates fixes so that fixes[*].End.IsValid().
It may be used as part of an analysis driver implementation.
Types ¶
type FixAction ¶
type FixAction struct {
Name string // e.g. "analyzer@package"
Pkg *types.Package // (for import removal)
Files []*ast.File
FileSet *token.FileSet
ReadFileFunc ReadFileFunc
Diagnostics []analysis.Diagnostic
}
FixAction abstracts a checker action (running one analyzer on one package) for the purposes of applying its diagnostics' fixes.
type JSONDiagnostic ¶
type JSONDiagnostic struct {
Category string `json:"category,omitempty"`
Posn string `json:"posn"` // e.g. "file.go:line:column"
Message string `json:"message"`
SuggestedFixes []JSONSuggestedFix `json:"suggested_fixes,omitempty"`
Related []JSONRelatedInformation `json:"related,omitempty"`
}
A JSONDiagnostic describes the JSON schema of an analysis.Diagnostic.
TODO(matloob): include End position if present.
type JSONRelatedInformation ¶
type JSONRelatedInformation struct {
Posn string `json:"posn"` // e.g. "file.go:line:column"
Message string `json:"message"`
}
A JSONRelated describes a secondary position and message related to a primary diagnostic.
TODO(adonovan): include End position if present.
type JSONSuggestedFix ¶
type JSONSuggestedFix struct {
Message string `json:"message"`
Edits []JSONTextEdit `json:"edits"`
}
A JSONSuggestedFix describes an edit that should be applied as a whole or not at all. It might contain multiple TextEdits/text_edits if the SuggestedFix consists of multiple non-contiguous edits.
type JSONTextEdit ¶
type JSONTextEdit struct {
Filename string `json:"filename"`
Start int `json:"start"`
End int `json:"end"`
New string `json:"new"`
}
A TextEdit describes the replacement of a portion of a file. Start and End are zero-based half-open indices into the original byte sequence of the file, and New is the new text.
type JSONTree ¶
A JSONTree is a mapping from package ID to analysis name to result. Each result is either a jsonError or a list of JSONDiagnostic.
type ReadFileFunc ¶
A ReadFileFunc is a function that returns the contents of a file, such as os.ReadFile.
func CheckedReadFile ¶
func CheckedReadFile(pass *analysis.Pass, readFile ReadFileFunc) ReadFileFunc
CheckedReadFile returns a wrapper around a Pass.ReadFile function that performs the appropriate checks.
Source Files