1 // Copyright 2019 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 package analysis
6 7 import "go/token"
8 9 // A Diagnostic is a message associated with a source location or range.
10 //
11 // An Analyzer may return a variety of diagnostics; the optional Category,
12 // which should be a constant, may be used to classify them.
13 // It is primarily intended to make it easy to look up documentation.
14 //
15 // All Pos values are interpreted relative to Pass.Fset. If End is
16 // provided, the diagnostic is specified to apply to the range between
17 // Pos and End.
18 type Diagnostic struct {
19 Pos token.Pos
20 End token.Pos // optional
21 Category string // optional
22 Message string
23 24 // URL is the optional location of a web page that provides
25 // additional documentation for this diagnostic.
26 //
27 // If URL is empty but a Category is specified, then the
28 // Analysis driver should treat the URL as "#"+Category.
29 //
30 // The URL may be relative. If so, the base URL is that of the
31 // Analyzer that produced the diagnostic;
32 // see https://pkg.go.dev/net/url#URL.ResolveReference.
33 URL string
34 35 // SuggestedFixes is an optional list of fixes to address the
36 // problem described by the diagnostic. Each one represents an
37 // alternative strategy, and should have a distinct and
38 // descriptive message; at most one may be applied.
39 //
40 // Fixes for different diagnostics should be treated as
41 // independent changes to the same baseline file state,
42 // analogous to a set of git commits all with the same parent.
43 // Combining fixes requires resolving any conflicts that
44 // arise, analogous to a git merge.
45 // Any conflicts that remain may be dealt with, depending on
46 // the tool, by discarding fixes, consulting the user, or
47 // aborting the operation.
48 SuggestedFixes []SuggestedFix
49 50 // Related contains optional secondary positions and messages
51 // related to the primary diagnostic.
52 Related []RelatedInformation
53 }
54 55 // RelatedInformation contains information related to a diagnostic.
56 // For example, a diagnostic that flags duplicated declarations of a
57 // variable may include one RelatedInformation per existing
58 // declaration.
59 type RelatedInformation struct {
60 Pos token.Pos
61 End token.Pos // optional
62 Message string
63 }
64 65 // A SuggestedFix is a code change associated with a Diagnostic that a
66 // user can choose to apply to their code. Usually the SuggestedFix is
67 // meant to fix the issue flagged by the diagnostic.
68 //
69 // The TextEdits must not overlap, nor contain edits for other
70 // packages. Edits need not be totally ordered, but the order
71 // determines how insertions at the same point will be applied.
72 type SuggestedFix struct {
73 // A verb phrase describing the fix, to be shown to
74 // a user trying to decide whether to accept it.
75 //
76 // Example: "Remove the surplus argument"
77 Message string
78 TextEdits []TextEdit
79 }
80 81 // A TextEdit represents the replacement of the code between Pos and End with the new text.
82 // Each TextEdit should apply to a single file. End should not be earlier in the file than Pos.
83 type TextEdit struct {
84 // For a pure insertion, End can either be set to Pos or token.NoPos.
85 Pos token.Pos
86 End token.Pos
87 NewText []byte
88 }
89