refactor: handles Cursor uniformly over all usage provenances (#64319)

This change should not change any behaviour, but it prepares for syntactic/search-based pagination.

Both syntactic and search based usages now return a "NextCursor", which is `Some` if there are more results of their provenance to be had. For now they always return `None` which preserves the current behaviour. The logic in `root_resolver` implements a state machine that transitions the cursor through the provenances and makes sure to skip provenances if the cursor in the request starts a certain state.

## Test plan

Tests continue to pass, no behavioral changes

Author: Christoph Hegemann

internal/codeintel/codenav/service.go

@@ -1140,7 +1140,9 @@ func (s SyntacticMatch) GetSurroundingContent() string {
 }
 
 type SyntacticUsagesResult struct {
-	Matches []SyntacticMatch
+	Matches                 []SyntacticMatch
+	PreviousSyntacticSearch PreviousSyntacticSearch
+	NextCursor              core.Option[UsagesCursor]
 }
 
 type UsagesForSymbolArgs struct {
@@ -1154,7 +1156,7 @@ func (s *Service) SyntacticUsages(
 	ctx context.Context,
 	gitTreeTranslator GitTreeTranslator,
 	args UsagesForSymbolArgs,
-) (SyntacticUsagesResult, PreviousSyntacticSearch, *SyntacticUsagesError) {
+) (SyntacticUsagesResult, *SyntacticUsagesError) {
 	// The `nil` in the second argument is here, because `With` does not work with custom error types.
 	ctx, trace, endObservation := s.operations.syntacticUsages.With(ctx, nil, observation.Args{Attrs: []attribute.KeyValue{
 		attribute.Int("repoId", int(args.Repo.ID)),
@@ -1166,7 +1168,7 @@ func (s *Service) SyntacticUsages(
 
 	upload, err := s.getSyntacticUpload(ctx, trace, args)
 	if err != nil {
-		return SyntacticUsagesResult{}, PreviousSyntacticSearch{}, err
+		return SyntacticUsagesResult{}, err
 	}
 	index := NewMappedIndexFromTranslator(s.lsifstore, gitTreeTranslator, upload, args.Commit)
 	return syntacticUsagesImpl(ctx, trace, s.searchClient, index, args)
@@ -1216,12 +1218,17 @@ func languageFromFilepath(trace observation.TraceLogger, path core.RepoRelPath)
 	return langs[0], nil
 }
 
+type SearchBasedUsagesResult struct {
+	Matches    []SearchBasedMatch
+	NextCursor core.Option[UsagesCursor]
+}
+
 func (s *Service) SearchBasedUsages(
 	ctx context.Context,
 	gitTreeTranslator GitTreeTranslator,
 	args UsagesForSymbolArgs,
 	previousSyntacticSearch core.Option[PreviousSyntacticSearch],
-) (matches []SearchBasedMatch, err error) {
+) (_ SearchBasedUsagesResult, err error) {
 	ctx, trace, endObservation := s.operations.searchBasedUsages.With(ctx, &err, observation.Args{Attrs: []attribute.KeyValue{
 		attribute.Int("repoId", int(args.Repo.ID)),
 		attribute.String("commit", string(args.Commit)),
@@ -1241,12 +1248,12 @@ func (s *Service) SearchBasedUsages(
 	} else {
 		language, err = languageFromFilepath(trace, args.Path)
 		if err != nil {
-			return nil, err
+			return SearchBasedUsagesResult{}, err
 		}
 
 		nameFromGit, err := s.symbolNameFromGit(ctx, args)
 		if err != nil {
-			return nil, err
+			return SearchBasedUsagesResult{}, err
 		}
 		symbolName = nameFromGit
 

internal/codeintel/codenav/service_syntactic_usages_test.go

@@ -22,13 +22,13 @@ func TestSearchBasedUsages_ResultWithoutSymbols(t *testing.T) {
 		WithFile("path.java", ChunkMatchWithLine(refRange, refRangeLineContent), ChunkMatch(refRange2)).
 		Build()
 
-	usages, err := searchBasedUsagesImpl(
+	result, err := searchBasedUsagesImpl(
 		context.Background(), observation.TestTraceLogger(log.NoOp()), mockSearchClient,
 		UsagesForSymbolArgs{}, "symbol", "Java", core.None[MappedIndex](),
 	)
 	require.NoError(t, err)
-	expectRanges(t, usages, refRange, refRange2)
-	expectContent(t, usages, refRange, refRangeLineContent)
+	expectRanges(t, result.Matches, refRange, refRange2)
+	expectContent(t, result.Matches, refRange, refRangeLineContent)
 }
 
 func TestSearchBasedUsages_ResultWithSymbol(t *testing.T) {
@@ -41,13 +41,13 @@ func TestSearchBasedUsages_ResultWithSymbol(t *testing.T) {
 		WithSymbols("path.java", defRange).
 		Build()
 
-	usages, err := searchBasedUsagesImpl(
+	result, err := searchBasedUsagesImpl(
 		context.Background(), observation.TestTraceLogger(log.NoOp()), mockSearchClient,
 		UsagesForSymbolArgs{}, "symbol", "Java", core.None[MappedIndex](),
 	)
 	require.NoError(t, err)
-	expectRanges(t, usages, refRange, refRange2, defRange)
-	expectDefinitionRanges(t, usages, defRange)
+	expectRanges(t, result.Matches, refRange, refRange2, defRange)
+	expectDefinitionRanges(t, result.Matches, defRange)
 }
 
 func TestSearchBasedUsages_SyntacticMatchesGetRemovedFromSearchBasedResults(t *testing.T) {
@@ -61,12 +61,12 @@ func TestSearchBasedUsages_SyntacticMatchesGetRemovedFromSearchBasedResults(t *t
 	upload, lsifStore := setupUpload(commit, "", doc("path.java", ref("ref", syntacticRange)))
 	fakeMappedIndex := NewMappedIndexFromTranslator(lsifStore, noopTranslator(), upload, commit)
 
-	usages, err := searchBasedUsagesImpl(
+	result, err := searchBasedUsagesImpl(
 		context.Background(), observation.TestTraceLogger(log.NoOp()), mockSearchClient,
 		UsagesForSymbolArgs{}, "symbol", "Java", core.Some(fakeMappedIndex),
 	)
 	require.NoError(t, err)
-	expectRanges(t, usages, commentRange)
+	expectRanges(t, result.Matches, commentRange)
 }
 
 func TestSyntacticUsages(t *testing.T) {
@@ -91,7 +91,7 @@ func TestSyntacticUsages(t *testing.T) {
 			ref("initial", initialRange)))
 	fakeMappedIndex := NewMappedIndexFromTranslator(lsifStore, noopTranslator(), upload, commit)
 
-	syntacticUsages, _, err := syntacticUsagesImpl(
+	syntacticUsages, err := syntacticUsagesImpl(
 		context.Background(), observation.TestTraceLogger(log.NoOp()),
 		mockSearchClient, fakeMappedIndex, UsagesForSymbolArgs{
 			Commit:      commit,
@@ -119,7 +119,7 @@ func TestSyntacticUsages_DocumentNotInIndex(t *testing.T) {
 		doc("initial.java",
 			ref("initial", initialRange)))
 	fakeMappedIndex := NewMappedIndexFromTranslator(lsifStore, noopTranslator(), upload, commit)
-	syntacticUsages, _, err := syntacticUsagesImpl(
+	syntacticUsages, err := syntacticUsagesImpl(
 		context.Background(), observation.TestTraceLogger(log.NoOp()),
 		mockSearchClient, fakeMappedIndex, UsagesForSymbolArgs{
 			Commit:      commit,
@@ -158,7 +158,7 @@ func TestSyntacticUsages_IndexCommitTranslated(t *testing.T) {
 			return r.CompareStrict(editedRange) == 0
 		}), upload, targetCommit)
 
-	syntacticUsages, _, err := syntacticUsagesImpl(
+	syntacticUsages, err := syntacticUsagesImpl(
 		context.Background(), observation.TestTraceLogger(log.NoOp()),
 		mockSearchClient, fakeMappedIndex, UsagesForSymbolArgs{
 			Commit:      targetCommit,

internal/codeintel/codenav/syntactic.go

@@ -371,24 +371,24 @@ func syntacticUsagesImpl(
 	searchClient searchclient.SearchClient,
 	mappedIndex MappedIndex,
 	args UsagesForSymbolArgs,
-) (SyntacticUsagesResult, PreviousSyntacticSearch, *SyntacticUsagesError) {
+) (SyntacticUsagesResult, *SyntacticUsagesError) {
 	searchSymbol, symErr := symbolAtRange(ctx, mappedIndex, args)
 	if symErr != nil {
-		return SyntacticUsagesResult{}, PreviousSyntacticSearch{}, &SyntacticUsagesError{
+		return SyntacticUsagesResult{}, &SyntacticUsagesError{
 			Code:            SU_NoSymbolAtRequestedRange,
 			UnderlyingError: symErr,
 		}
 	}
 	language, langErr := languageFromFilepath(trace, args.Path)
 	if langErr != nil {
-		return SyntacticUsagesResult{}, PreviousSyntacticSearch{}, &SyntacticUsagesError{
+		return SyntacticUsagesResult{}, &SyntacticUsagesError{
 			Code:            SU_FailedToSearch,
 			UnderlyingError: langErr,
 		}
 	}
 	symbolName, ok := nameFromGlobalSymbol(searchSymbol)
 	if !ok {
-		return SyntacticUsagesResult{}, PreviousSyntacticSearch{}, &SyntacticUsagesError{
+		return SyntacticUsagesResult{}, &SyntacticUsagesError{
 			Code:            SU_FailedToSearch,
 			UnderlyingError: errors.New("can't find syntactic occurrences for locals via search"),
 		}
@@ -401,7 +401,7 @@ func syntacticUsagesImpl(
 	}
 	candidateMatches, searchErr := findCandidateOccurrencesViaSearch(ctx, trace, searchClient, searchCoords)
 	if searchErr != nil {
-		return SyntacticUsagesResult{}, PreviousSyntacticSearch{}, &SyntacticUsagesError{
+		return SyntacticUsagesResult{}, &SyntacticUsagesError{
 			Code:            SU_FailedToSearch,
 			UnderlyingError: searchErr,
 		}
@@ -426,16 +426,20 @@ func syntacticUsagesImpl(
 		return slices.Concat(results...), nil
 	})
 	if err != nil {
-		return SyntacticUsagesResult{}, PreviousSyntacticSearch{}, &SyntacticUsagesError{
+		return SyntacticUsagesResult{}, &SyntacticUsagesError{
 			Code:            SU_Fatal,
 			UnderlyingError: err,
 		}
 	}
 
-	return SyntacticUsagesResult{Matches: slices.Concat(results...)}, PreviousSyntacticSearch{
-		MappedIndex: mappedIndex,
-		SymbolName:  symbolName,
-		Language:    language,
+	return SyntacticUsagesResult{
+		Matches: slices.Concat(results...),
+		PreviousSyntacticSearch: PreviousSyntacticSearch{
+			MappedIndex: mappedIndex,
+			SymbolName:  symbolName,
+			Language:    language,
+		},
+		NextCursor: core.None[UsagesCursor](),
 	}, nil
 }
 
@@ -449,7 +453,7 @@ func searchBasedUsagesImpl(
 	symbolName string,
 	language string,
 	syntacticIndex core.Option[MappedIndex],
-) (matches []SearchBasedMatch, err error) {
+) (_ SearchBasedUsagesResult, err error) {
 	searchCoords := searchArgs{
 		repo:       args.Repo.Name,
 		commit:     args.Commit,
@@ -474,7 +478,7 @@ func searchBasedUsagesImpl(
 	})
 	wg.Wait()
 	if matchResults.err != nil {
-		return nil, matchResults.err
+		return SearchBasedUsagesResult{}, matchResults.err
 	}
 	if symbolResults.err != nil {
 		trace.Warn("Failed to run symbol search, will not mark any search-based usages as definitions", log.Error(symbolResults.err))
@@ -513,5 +517,8 @@ func searchBasedUsagesImpl(
 		}
 		return slices.Concat(results...)
 	})
-	return slices.Concat(results...), nil
+	return SearchBasedUsagesResult{
+		Matches:    slices.Concat(results...),
+		NextCursor: core.None[UsagesCursor](),
+	}, nil
 }

internal/codeintel/codenav/transport/graphql/iface.go

@@ -31,8 +31,8 @@ type CodeNavService interface {
 	//
 	// Subsequent calls can pass the returned cursor (if non-empty) via args.Cursor.
 	PreciseUsages(ctx context.Context, requestState codenav.RequestState, args codenav.UsagesForSymbolResolvedArgs) (_ []shared.UploadUsage, nextCursor core.Option[codenav.UsagesCursor], err error)
-	SyntacticUsages(context.Context, codenav.GitTreeTranslator, codenav.UsagesForSymbolArgs) (codenav.SyntacticUsagesResult, codenav.PreviousSyntacticSearch, *codenav.SyntacticUsagesError)
-	SearchBasedUsages(context.Context, codenav.GitTreeTranslator, codenav.UsagesForSymbolArgs, core.Option[codenav.PreviousSyntacticSearch]) ([]codenav.SearchBasedMatch, error)
+	SyntacticUsages(context.Context, codenav.GitTreeTranslator, codenav.UsagesForSymbolArgs) (codenav.SyntacticUsagesResult, *codenav.SyntacticUsagesError)
+	SearchBasedUsages(context.Context, codenav.GitTreeTranslator, codenav.UsagesForSymbolArgs, core.Option[codenav.PreviousSyntacticSearch]) (codenav.SearchBasedUsagesResult, error)
 }
 
 var _ CodeNavService = &codenav.Service{}