feat(api): mark speculative xrefs (#5959)

Speculative xrefs are those that may be overly conservative or not
strictly representative of the static source code.  Examples include
calls that may occur through dynamic dispatch and ref/writes that may
occur later through a callable (ref/writes/thunk).

kythe/go/services/xrefs/xrefs.go

@@ -180,6 +180,11 @@ func IsCallerKind(requestedKind xpb.CrossReferencesRequest_CallerKind, edgeKind
 	}
 }
 
+// IsSpeculative returns whether the edge kind is considered speculative.
+func IsSpeculative(edgeKind string) bool {
+	return edgeKind == internalCallerKindOverride || strings.HasSuffix(edgeKind, "/thunk")
+}
+
 // ConvertFilters converts each filter glob into an equivalent regexp.
 func ConvertFilters(filters []string) []*regexp.Regexp {
 	var patterns []*regexp.Regexp

kythe/go/serving/xrefs/xrefs.go

@@ -1363,6 +1363,8 @@ func (s *refStats) addCallers(crs *xpb.CrossReferencesReply_CrossReferenceSet, g
 			Anchor: converter.Convert(c.Caller).Anchor,
 			Ticket: c.SemanticCaller,
 			Site:   make([]*xpb.Anchor, 0, len(c.Callsite)),
+
+			Speculative: xrefs.IsSpeculative(grp.GetKind()),
 		}
 		ra.MarkedSource = c.MarkedSource
 		for _, site := range c.Callsite {
@@ -1474,6 +1476,8 @@ func (s *refStats) addAnchors(to *[]*xpb.CrossReferencesReply_RelatedAnchor, grp
 			Anchor: scope,
 			Ticket: sr.SemanticScope,
 			Site:   make([]*xpb.Anchor, 0, len(sr.Reference)),
+
+			Speculative: xrefs.IsSpeculative(grp.GetKind()),
 		}
 		ra.MarkedSource = sr.MarkedSource
 		refs := sr.GetReference()
@@ -1528,7 +1532,10 @@ func (c *anchorConverter) Convert(a *srvpb.ExpandedAnchor) *xpb.CrossReferencesR
 		SnippetSpan: a.SnippetSpan,
 		BuildConfig: a.BuildConfiguration,
 		Revision:    fileInfo.GetRevision(),
-	}}
+	},
+
+		Speculative: xrefs.IsSpeculative(a.GetKind()),
+	}
 }
 
 type documentConverter struct {

kythe/go/serving/xrefs/xrefs_test.go

@@ -2865,6 +2865,7 @@ func TestCrossReferencesOverrideCallers(t *testing.T) {
 				Parent: "kythe:?path=someFile",
 			}},
 		}, {
+			Speculative: true,
 			Anchor: &xpb.Anchor{
 				Ticket: "kythe:?path=someFile#someOverrideCallerAnchor1",
 				Parent: "kythe:?path=someFile",
@@ -2876,6 +2877,7 @@ func TestCrossReferencesOverrideCallers(t *testing.T) {
 				Span:   arbitrarySpan,
 			}},
 		}, {
+			Speculative: true,
 			Anchor: &xpb.Anchor{
 				Ticket: "kythe:?path=someFile#someOverrideCallerAnchor2",
 				Parent: "kythe:?path=someFile",

kythe/proto/xref.proto

@@ -345,7 +345,8 @@ message CrossReferencesRequest {
     // Callgraph information will be populated in the CrossReferencesReply.
     DIRECT_CALLERS = 1;
     // Callgraph information will be populated in the CrossReferencesReply.
-    // Calls to override-related functions will also be considered.
+    // Calls to override-related functions will also be considered and each
+    // RelatedAnchor will be marked as speculative.
     OVERRIDE_CALLERS = 2;
   }
 
@@ -539,6 +540,11 @@ message CrossReferencesReply {
     // references.
     string ticket = 4;
 
+    // Whether the anchor, and its sites, are speculative and may not be precise
+    // with respect to a program's execution.  Examples include callsites that
+    // may occur through dynamic dispatch or ref/writes/thunk locations.
+    bool speculative = 6;
+
     reserved 2;
   }