go/analysis/internal/analysisflags: add RelatedInformation JSON

This change adds RelatedInformation to the JSON output
of the analysis tools.

(None of the analyzers we maintain currently uses this field.)

Also, tighten up the doc comments.

Fixes golang/go#64548

Change-Id: I7087858083c1eec917e00fe840c2a5aa8eb2e898
Reviewed-on: https://go-review.googlesource.com/c/tools/+/556820
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Matloob <matloob@golang.org>

go/analysis/diagnostic.go

@@ -31,14 +31,14 @@ type Diagnostic struct {
 	// see https://pkg.go.dev/net/url#URL.ResolveReference.
 	URL string
 
-	// SuggestedFixes contains suggested fixes for a diagnostic
-	// which can be used to perform edits to a file that address
-	// the diagnostic.
-	//
-	// Diagnostics should not contain SuggestedFixes that overlap.
-	SuggestedFixes []SuggestedFix // optional
+	// SuggestedFixes is an optional list of fixes to address the
+	// problem described by the diagnostic, each one representing
+	// an alternative strategy; at most one may be applied.
+	SuggestedFixes []SuggestedFix
 
-	Related []RelatedInformation // optional
+	// Related contains optional secondary positions and messages
+	// related to the primary diagnostic.
+	Related []RelatedInformation
 }
 
 // RelatedInformation contains information related to a diagnostic.
@@ -55,8 +55,7 @@ type RelatedInformation struct {
 // user can choose to apply to their code. Usually the SuggestedFix is
 // meant to fix the issue flagged by the diagnostic.
 //
-// TextEdits for a SuggestedFix should not overlap,
-// nor contain edits for other packages.
+// The TextEdits must not overlap, nor contain edits for other packages.
 type SuggestedFix struct {
 	// A description for this suggested fix to be shown to a user deciding
 	// whether to accept it.

go/analysis/internal/analysisflags/flags.go

@@ -362,15 +362,24 @@ type JSONSuggestedFix struct {
 	Edits   []JSONTextEdit `json:"edits"`
 }
 
-// A JSONDiagnostic can be used to encode and decode analysis.Diagnostics to and
-// from JSON.
-// TODO(matloob): Should the JSON diagnostics contain ranges?
-// If so, how should they be formatted?
+// A JSONDiagnostic describes the JSON schema of an analysis.Diagnostic.
+//
+// TODO(matloob): include End position if present.
 type JSONDiagnostic struct {
-	Category       string             `json:"category,omitempty"`
-	Posn           string             `json:"posn"`
-	Message        string             `json:"message"`
-	SuggestedFixes []JSONSuggestedFix `json:"suggested_fixes,omitempty"`
+	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 JSONRelated describes a secondary position and message related to
+// a primary diagnostic.
+//
+// TODO(adonovan): include End position if present.
+type JSONRelatedInformation struct {
+	Posn    string `json:"posn"` // e.g. "file.go:line:column"
+	Message string `json:"message"`
 }
 
 // Add adds the result of analysis 'name' on package 'id'.
@@ -401,11 +410,19 @@ func (tree JSONTree) Add(fset *token.FileSet, id, name string, diags []analysis.
 					Edits:   edits,
 				})
 			}
+			var related []JSONRelatedInformation
+			for _, r := range f.Related {
+				related = append(related, JSONRelatedInformation{
+					Posn:    fset.Position(r.Pos).String(),
+					Message: r.Message,
+				})
+			}
 			jdiag := JSONDiagnostic{
 				Category:       f.Category,
 				Posn:           fset.Position(f.Pos).String(),
 				Message:        f.Message,
 				SuggestedFixes: fixes,
+				Related:        related,
 			}
 			diagnostics = append(diagnostics, jdiag)
 		}