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
5package analysis
6
7import "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.
18type 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
37	// an alternative strategy; at most one may be applied.
38	//
39	// Fixes for different diagnostics should be treated as
40	// independent changes to the same baseline file state,
41	// analogous to a set of git commits all with the same parent.
42	// Combining fixes requires resolving any conflicts that
43	// arise, analogous to a git merge.
44	// Any conflicts that remain may be dealt with, depending on
45	// the tool, by discarding fixes, consulting the user, or
46	// aborting the operation.
47	SuggestedFixes []SuggestedFix
48
49	// Related contains optional secondary positions and messages
50	// related to the primary diagnostic.
51	Related []RelatedInformation
52}
53
54// RelatedInformation contains information related to a diagnostic.
55// For example, a diagnostic that flags duplicated declarations of a
56// variable may include one RelatedInformation per existing
57// declaration.
58type RelatedInformation struct {
59	Pos     token.Pos
60	End     token.Pos // optional
61	Message string
62}
63
64// A SuggestedFix is a code change associated with a Diagnostic that a
65// user can choose to apply to their code. Usually the SuggestedFix is
66// meant to fix the issue flagged by the diagnostic.
67//
68// The TextEdits must not overlap, nor contain edits for other packages.
69type SuggestedFix struct {
70	// A verb phrase describing the fix, to be shown to
71	// a user trying to decide whether to accept it.
72	//
73	// Example: "Remove the surplus argument"
74	Message   string
75	TextEdits []TextEdit
76}
77
78// A TextEdit represents the replacement of the code between Pos and End with the new text.
79// Each TextEdit should apply to a single file. End should not be earlier in the file than Pos.
80type TextEdit struct {
81	// For a pure insertion, End can either be set to Pos or token.NoPos.
82	Pos     token.Pos
83	End     token.Pos
84	NewText []byte
85}
86