diagnostic.go

     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
View as plain text