internal/api: implement package symbols endpoint

- Introduce a new ServePackageSymbols handler that utilizes the new
  db.GetSymbols method.
- Consolidated module resolution logic shared by ServePackages into
  resolveModulePath.
- Updated Datasource with GetSymbols, which provides a more efficient
  way to retrieve all symbols for a package at a given version and build
  context. This differs from the existing getPackageSymbols, since that
  will return symbols for the latest release/compatible version.
- Refactored packageSymbolQueryJoin into a generic helper by removing
  hardcoded version filters. This allows GetSymbols to query for any
  specific version, while getPackageSymbols was updated to explicitly
  include release-only filters to preserve its existing behavior.
- GetSymbols still utilizes the same underlying packageSymbolQueryJoin,
  but it will also attempt to match the most relevant BuildContext for
  the query. It will also provide a mapping of parent and child symbols.

Change-Id: Ib18d2511d24ac6bc5b75c7b3809c4ce126245036
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/754864
Auto-Submit: Ethan Lee <ethanalee@google.com>
kokoro-CI: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

7 files changed, 380 insertions, 77 deletions

diff --git a/internal/api/api.go b/internal/api/api.go
index 4f4fcf7b..edd758e1 100644
--- a/internal/api/api.go
+++ b/internal/api/api.go
@@ -42,37 +42,15 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource
 		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
 	}
 
-	requestedVersion := params.Version
-	if requestedVersion == "" {
-		requestedVersion = version.Latest
-	}
-
-	var um *internal.UnitMeta
-	modulePath := params.Module
-	if modulePath == "" {
-		// Handle potential ambiguity if module is not specified.
-		candidates := internal.CandidateModulePaths(pkgPath)
-		var validCandidates []Candidate
-		for _, mp := range candidates {
-			// Check if this module actually exists and contains the package at the requested version.
-			if m, err := ds.GetUnitMeta(r.Context(), pkgPath, mp, requestedVersion); err == nil {
-				um = m
-				validCandidates = append(validCandidates, Candidate{
-					ModulePath:  mp,
-					PackagePath: pkgPath,
-				})
-			} else if !errors.Is(err, derrors.NotFound) {
-				return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
-			}
-		}
-
-		if len(validCandidates) > 1 {
-			return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", validCandidates)
-		}
-		if len(validCandidates) == 0 {
-			return serveErrorJSON(w, http.StatusNotFound, "package not found", nil)
+	um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version)
+	if err != nil {
+		if errors.Is(err, derrors.NotFound) {
+			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
 		}
-		modulePath = validCandidates[0].ModulePath
+		return err
+	}
+	if len(candidates) > 0 {
+		return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates)
 	}
 
 	// Use GetUnit to get the requested data.
@@ -88,44 +66,9 @@ func ServePackage(w http.ResponseWriter, r *http.Request, ds internal.DataSource
 	}
 
 	bc := internal.BuildContext{GOOS: params.GOOS, GOARCH: params.GOARCH}
-	var unit *internal.Unit
-	if um != nil {
-		var err error
-		unit, err = ds.GetUnit(r.Context(), um, fs, bc)
-		if err != nil {
-			return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
-		}
-	} else if modulePath != "" && modulePath != internal.UnknownModulePath && !needsResolution(requestedVersion) {
-		// This block is reachable if the user explicitly provided a module path and a
-		// concrete version in the query parameters, skipping the candidate search.
-		um = &internal.UnitMeta{
-			Path: pkgPath,
-			ModuleInfo: internal.ModuleInfo{
-				ModulePath: modulePath,
-				Version:    requestedVersion,
-			},
-		}
-		var err error
-		unit, err = ds.GetUnit(r.Context(), um, fs, bc)
-		if err != nil && !errors.Is(err, derrors.NotFound) {
-			return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
-		}
-	}
-
-	if unit == nil {
-		// Fallback: Resolve the version or find the module using GetUnitMeta.
-		var err error
-		um, err = ds.GetUnitMeta(r.Context(), pkgPath, modulePath, requestedVersion)
-		if err != nil {
-			if errors.Is(err, derrors.NotFound) {
-				return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
-			}
-			return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
-		}
-		unit, err = ds.GetUnit(r.Context(), um, fs, bc)
-		if err != nil {
-			return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
-		}
+	unit, err := ds.GetUnit(r.Context(), um, fs, bc)
+	if err != nil {
+		return serveErrorJSON(w, http.StatusInternalServerError, err.Error(), nil)
 	}
 
 	// Process documentation, including synopsis.
@@ -393,9 +336,109 @@ func ServeSearch(w http.ResponseWriter, r *http.Request, ds internal.DataSource)
 	return serveJSON(w, http.StatusOK, resp)
 }
 
-// needsResolution reports whether the version string is a sentinel like "latest" or "master".
-func needsResolution(v string) bool {
-	return v == version.Latest || v == version.Master || v == version.Main
+// ServePackageSymbols handles requests for the v1 package symbols endpoint.
+func ServePackageSymbols(w http.ResponseWriter, r *http.Request, ds internal.DataSource) (err error) {
+	defer derrors.Wrap(&err, "ServePackageSymbols")
+
+	pkgPath := strings.TrimPrefix(r.URL.Path, "/v1/symbols/")
+	pkgPath = strings.Trim(pkgPath, "/")
+	if pkgPath == "" {
+		return serveErrorJSON(w, http.StatusBadRequest, "missing package path", nil)
+	}
+
+	var params SymbolsParams
+	if err := ParseParams(r.URL.Query(), &params); err != nil {
+		return serveErrorJSON(w, http.StatusBadRequest, err.Error(), nil)
+	}
+
+	um, candidates, err := resolveModulePath(r, ds, pkgPath, params.Module, params.Version)
+	if err != nil {
+		if errors.Is(err, derrors.NotFound) {
+			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
+		}
+		return err
+	}
+	if len(candidates) > 0 {
+		return serveErrorJSON(w, http.StatusBadRequest, "ambiguous package path", candidates)
+	}
+
+	bc := internal.BuildContext{GOOS: params.GOOS, GOARCH: params.GOARCH}
+	syms, err := ds.GetSymbols(r.Context(), pkgPath, um.ModulePath, um.Version, bc)
+	if err != nil {
+		if errors.Is(err, derrors.NotFound) {
+			return serveErrorJSON(w, http.StatusNotFound, err.Error(), nil)
+		}
+		return err
+	}
+
+	limit := params.Limit
+	if limit <= 0 {
+		limit = 100
+	}
+	if limit > len(syms) {
+		limit = len(syms)
+	}
+
+	var items []Symbol
+	for _, s := range syms[:limit] {
+		items = append(items, Symbol{
+			ModulePath: um.ModulePath,
+			Version:    um.Version,
+			Name:       s.Name,
+			Kind:       string(s.Kind),
+			Synopsis:   s.Synopsis,
+			Parent:     s.ParentName,
+		})
+	}
+
+	resp := PaginatedResponse[Symbol]{
+		Items: items,
+		Total: len(syms),
+	}
+
+	return serveJSON(w, http.StatusOK, resp)
+}
+
+// resolveModulePath determines the correct module path for a given package path and version.
+// If the module path is not provided, it searches through potential candidate module paths
+// derived from the package path. If multiple valid modules contain the package, it returns
+// a list of candidates to help the user disambiguate the request.
+func resolveModulePath(r *http.Request, ds internal.DataSource, pkgPath, modulePath, requestedVersion string) (*internal.UnitMeta, []Candidate, error) {
+	if requestedVersion == "" {
+		requestedVersion = version.Latest
+	}
+	if modulePath == "" {
+		// Handle potential ambiguity if module is not specified.
+		candidates := internal.CandidateModulePaths(pkgPath)
+		var validCandidates []Candidate
+		var foundUM *internal.UnitMeta
+		for _, mp := range candidates {
+			// Check if this module actually exists and contains the package at the requested version.
+			if m, err := ds.GetUnitMeta(r.Context(), pkgPath, mp, requestedVersion); err == nil {
+				foundUM = m
+				validCandidates = append(validCandidates, Candidate{
+					ModulePath:  mp,
+					PackagePath: pkgPath,
+				})
+			} else if !errors.Is(err, derrors.NotFound) {
+				return nil, nil, err
+			}
+		}
+
+		if len(validCandidates) > 1 {
+			return nil, validCandidates, nil
+		}
+		if len(validCandidates) == 0 {
+			return nil, nil, derrors.NotFound
+		}
+		return foundUM, nil, nil
+	}
+
+	um, err := ds.GetUnitMeta(r.Context(), pkgPath, modulePath, requestedVersion)
+	if err != nil {
+		return nil, nil, err
+	}
+	return um, nil, nil
 }
 
 func serveJSON(w http.ResponseWriter, status int, data any) error {
diff --git a/internal/api/api_test.go b/internal/api/api_test.go
index 595a3d25..50c11327 100644
--- a/internal/api/api_test.go
+++ b/internal/api/api_test.go
@@ -289,7 +289,7 @@ func TestServeModule(t *testing.T) {
 			w := httptest.NewRecorder()
 
 			err := ServeModule(w, r, ds)
-			if err != nil {
+			if err != nil && w.Code != test.wantStatus {
 				t.Fatalf("ServeModule returned error: %v", err)
 			}
 
@@ -357,7 +357,7 @@ func TestServeModuleVersions(t *testing.T) {
 			w := httptest.NewRecorder()
 
 			err := ServeModuleVersions(w, r, ds)
-			if err != nil {
+			if err != nil && w.Code != test.wantStatus {
 				t.Fatalf("ServeModuleVersions returned error: %v", err)
 			}
 
@@ -413,7 +413,7 @@ func TestServeModulePackages(t *testing.T) {
 			w := httptest.NewRecorder()
 
 			err := ServeModulePackages(w, r, ds)
-			if err != nil {
+			if err != nil && w.Code != test.wantStatus {
 				t.Fatalf("ServeModulePackages returned error: %v", err)
 			}
 
@@ -589,3 +589,124 @@ func TestServeSearchPagination(t *testing.T) {
 		})
 	}
 }
+
+func TestServePackageSymbols(t *testing.T) {
+	ctx := context.Background()
+	ds := fakedatasource.New()
+
+	const (
+		pkgPath    = "example.com/pkg"
+		modulePath = "example.com"
+		version    = "v1.0.0"
+	)
+
+	ds.MustInsertModule(ctx, &internal.Module{
+		ModuleInfo: internal.ModuleInfo{ModulePath: modulePath, Version: version},
+		Units: []*internal.Unit{{
+			UnitMeta: internal.UnitMeta{
+				Path:       pkgPath,
+				ModuleInfo: internal.ModuleInfo{ModulePath: modulePath, Version: version},
+				Name:       "pkg",
+			},
+			Symbols: map[internal.BuildContext][]*internal.Symbol{
+				{GOOS: "linux", GOARCH: "amd64"}: {
+					{
+						SymbolMeta: internal.SymbolMeta{Name: "LinuxSym", Kind: internal.SymbolKindFunction},
+						GOOS:       "linux",
+						GOARCH:     "amd64",
+					},
+					{
+						SymbolMeta: internal.SymbolMeta{Name: "T", Kind: internal.SymbolKindType},
+						GOOS:       "linux",
+						GOARCH:     "amd64",
+						Children: []*internal.SymbolMeta{
+							{Name: "T.M", Kind: internal.SymbolKindMethod, ParentName: "T"},
+						},
+					},
+				},
+				{GOOS: "windows", GOARCH: "amd64"}: {
+					{SymbolMeta: internal.SymbolMeta{Name: "WindowsSym", Kind: internal.SymbolKindFunction}, GOOS: "windows", GOARCH: "amd64"},
+				},
+				{GOOS: "js", GOARCH: "wasm"}: {
+					{SymbolMeta: internal.SymbolMeta{Name: "WasmSym", Kind: internal.SymbolKindFunction}, GOOS: "js", GOARCH: "wasm"},
+				},
+			},
+		}},
+	})
+
+	for _, test := range []struct {
+		name       string
+		url        string
+		wantStatus int
+		wantCount  int
+		wantName   string // Check name of the first symbol to verify build context
+	}{
+		{
+			name:       "default best match (linux)",
+			url:        "/v1/symbols/example.com/pkg?version=v1.0.0",
+			wantStatus: http.StatusOK,
+			wantCount:  2,
+			wantName:   "LinuxSym",
+		},
+		{
+			name:       "explicit linux",
+			url:        "/v1/symbols/example.com/pkg?version=v1.0.0&goos=linux&goarch=amd64",
+			wantStatus: http.StatusOK,
+			wantCount:  2,
+			wantName:   "LinuxSym",
+		},
+		{
+			name:       "version latest",
+			url:        "/v1/symbols/example.com/pkg?version=latest",
+			wantStatus: http.StatusOK,
+			wantCount:  2,
+			wantName:   "LinuxSym",
+		},
+		{
+			name:       "explicit windows",
+			url:        "/v1/symbols/example.com/pkg?version=v1.0.0&goos=windows&goarch=amd64",
+			wantStatus: http.StatusOK,
+			wantCount:  1,
+			wantName:   "WindowsSym",
+		},
+		{
+			name:       "explicit wasm",
+			url:        "/v1/symbols/example.com/pkg?version=v1.0.0&goos=js&goarch=wasm",
+			wantStatus: http.StatusOK,
+			wantCount:  1,
+			wantName:   "WasmSym",
+		},
+		{
+			name:       "not found build context",
+			url:        "/v1/symbols/example.com/pkg?version=v1.0.0&goos=darwin&goarch=amd64",
+			wantStatus: http.StatusNotFound,
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			r := httptest.NewRequest("GET", test.url, nil)
+			w := httptest.NewRecorder()
+
+			err := ServePackageSymbols(w, r, ds)
+			if err != nil && w.Code != test.wantStatus {
+				t.Fatalf("ServePackageSymbols returned error: %v", err)
+			}
+
+			if w.Code != test.wantStatus {
+				t.Errorf("status = %d, want %d. Body: %s", w.Code, test.wantStatus, w.Body.String())
+			}
+
+			if test.wantStatus == http.StatusOK {
+				var got PaginatedResponse[Symbol]
+				if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+					t.Fatalf("json.Unmarshal: %v", err)
+				}
+				if len(got.Items) != test.wantCount {
+					t.Errorf("count = %d, want %d", len(got.Items), test.wantCount)
+				}
+				if test.wantName != "" && got.Items[0].Name != test.wantName {
+					t.Errorf("first symbol = %q, want %q", got.Items[0].Name, test.wantName)
+				}
+			}
+		})
+	}
+}
diff --git a/internal/datasource.go b/internal/datasource.go
index f6bf8c84..59f0afa1 100644
--- a/internal/datasource.go
+++ b/internal/datasource.go
@@ -95,6 +95,8 @@ type DataSource interface {
 	GetVersionsForPath(ctx context.Context, path string) ([]*ModuleInfo, error)
 	// GetModulePackages returns a list of packages in the given module version.
 	GetModulePackages(ctx context.Context, modulePath, version string) ([]*PackageMeta, error)
+	// GetSymbols returns symbols for the given unit and build context.
+	GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc BuildContext) ([]*Symbol, error)
 
 	// SearchSupport reports the search types supported by this datasource.
 	SearchSupport() SearchSupport
diff --git a/internal/fetchdatasource/fetchdatasource.go b/internal/fetchdatasource/fetchdatasource.go
index 1643d009..7a5f5669 100644
--- a/internal/fetchdatasource/fetchdatasource.go
+++ b/internal/fetchdatasource/fetchdatasource.go
@@ -433,3 +433,23 @@ func (ds *FetchDataSource) GetModulePackages(ctx context.Context, modulePath, ve
 	}
 	return metas, nil
 }
+
+// GetSymbols returns symbols for the given unit and build context.
+func (ds *FetchDataSource) GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc internal.BuildContext) (_ []*internal.Symbol, err error) {
+	defer derrors.Wrap(&err, "FetchDataSource.GetSymbols(%q, %q, %q, %v)", pkgPath, modulePath, version, bc)
+
+	m, err := ds.getModule(ctx, modulePath, version)
+	if err != nil {
+		return nil, err
+	}
+	unit, err := ds.findUnit(ctx, m, pkgPath)
+	if err != nil {
+		return nil, err
+	}
+
+	doc := matchingDoc(unit.Documentation, bc)
+	if doc == nil || len(doc.API) == 0 {
+		return nil, derrors.NotFound
+	}
+	return doc.API, nil
+}
diff --git a/internal/frontend/server.go b/internal/frontend/server.go
index a1fd4516..6f4e5a9d 100644
--- a/internal/frontend/server.go
+++ b/internal/frontend/server.go
@@ -237,6 +237,7 @@ func (s *Server) Install(handle func(string, http.Handler), cacher Cacher, authV
 	handle("GET /files/", http.StripPrefix("/files", s.fileMux))
 	handle("GET /vuln/", vulnHandler)
 	handle("GET /v1/package/", s.errorHandler(api.ServePackage))
+	handle("GET /v1/symbols/", s.errorHandler(api.ServePackageSymbols))
 	handle("GET /v1/module/", s.errorHandler(api.ServeModule))
 	handle("GET /v1/versions/", s.errorHandler(api.ServeModuleVersions))
 	handle("GET /v1/packages/", s.errorHandler(api.ServeModulePackages))
diff --git a/internal/postgres/package_symbol.go b/internal/postgres/package_symbol.go
index aaa28267..4d99b07c 100644
--- a/internal/postgres/package_symbol.go
+++ b/internal/postgres/package_symbol.go
@@ -8,6 +8,7 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"sort"
 
 	"github.com/Masterminds/squirrel"
 	"golang.org/x/pkgsite/internal"
@@ -16,6 +17,93 @@ import (
 	"golang.org/x/pkgsite/internal/middleware/stats"
 )
 
+// GetSymbols returns all of the symbols for a given package path and module path.
+func (db *DB) GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc internal.BuildContext) (_ []*internal.Symbol, err error) {
+	defer derrors.Wrap(&err, "DB.GetSymbols(ctx, %q, %q, %q, %v)", pkgPath, modulePath, version, bc)
+	defer stats.Elapsed(ctx, "DB.GetSymbols")()
+
+	query := packageSymbolQueryJoin(
+		squirrel.Select(
+			"s1.name AS symbol_name",
+			"s2.name AS parent_symbol_name",
+			"ps.section",
+			"ps.type",
+			"ps.synopsis",
+			"d.goos",
+			"d.goarch"), pkgPath, modulePath).
+		Where(squirrel.Eq{"m.version": version}).
+		OrderBy("CASE WHEN ps.type='Type' THEN 0 ELSE 1 END").
+		OrderBy("s1.name")
+
+	q, args, err := query.PlaceholderFormat(squirrel.Dollar).ToSql()
+	if err != nil {
+		return nil, err
+	}
+
+	resultsByBC := make(map[internal.BuildContext][]internal.SymbolMeta)
+	collect := func(rows *sql.Rows) error {
+		var (
+			name, parentName, synopsis, goos, goarch string
+			section                                  internal.SymbolSection
+			kind                                     internal.SymbolKind
+		)
+		if err := rows.Scan(&name, &parentName, &section, &kind, &synopsis, &goos, &goarch); err != nil {
+			return fmt.Errorf("row.Scan(): %v", err)
+		}
+		rowBC := internal.BuildContext{GOOS: goos, GOARCH: goarch}
+		if bc.Match(rowBC) {
+			resultsByBC[rowBC] = append(resultsByBC[rowBC], internal.SymbolMeta{
+				Name:       name,
+				ParentName: parentName,
+				Section:    section,
+				Kind:       kind,
+				Synopsis:   synopsis,
+			})
+		}
+		return nil
+	}
+
+	if err := db.db.RunQuery(ctx, q, collect, args...); err != nil {
+		return nil, err
+	}
+
+	if len(resultsByBC) == 0 {
+		return nil, derrors.NotFound
+	}
+
+	// Find the best build context among those that matched.
+	var matchedBCs []internal.BuildContext
+	for b := range resultsByBC {
+		matchedBCs = append(matchedBCs, b)
+	}
+	sort.Slice(matchedBCs, func(i, j int) bool {
+		return internal.CompareBuildContexts(matchedBCs[i], matchedBCs[j]) < 0
+	})
+	bestBC := matchedBCs[0]
+
+	var symbols []*internal.Symbol
+	symbolMap := make(map[string]*internal.Symbol)
+	rows := resultsByBC[bestBC]
+	for i := range rows {
+		sm := rows[i]
+		if sm.ParentName != "" && sm.ParentName != sm.Name {
+			if parent, ok := symbolMap[sm.ParentName]; ok {
+				parent.Children = append(parent.Children, &rows[i])
+				continue
+			}
+		}
+		// Treat as top-level if no parent or parent not found in this build context.
+		s := &internal.Symbol{
+			SymbolMeta: sm,
+			GOOS:       bestBC.GOOS,
+			GOARCH:     bestBC.GOARCH,
+		}
+		symbols = append(symbols, s)
+		symbolMap[sm.Name] = s
+	}
+	return symbols, nil
+}
+
 // getPackageSymbols returns all of the symbols for a given package path and module path.
 func getPackageSymbols(ctx context.Context, ddb *database.DB, packagePath, modulePath string,
 ) (_ *internal.SymbolHistory, err error) {
@@ -32,6 +120,8 @@ func getPackageSymbols(ctx context.Context, ddb *database.DB, packagePath, modul
 			"m.version",
 			"d.goos",
 			"d.goarch"), packagePath, modulePath).
+		Where("NOT m.incompatible").
+		Where(squirrel.Eq{"m.version_type": "release"}).
 		OrderBy("CASE WHEN ps.type='Type' THEN 0 ELSE 1 END").
 		OrderBy("s1.name")
 	q, args, err := query.PlaceholderFormat(squirrel.Dollar).ToSql()
@@ -64,9 +154,7 @@ func packageSymbolQueryJoin(query squirrel.SelectBuilder, pkgPath, modulePath st
 		Join("symbol_names s1 ON ps.symbol_name_id = s1.id").
 		Join("symbol_names s2 ON ps.parent_symbol_name_id = s2.id").
 		Where(squirrel.Eq{"p1.path": pkgPath}).
-		Where(squirrel.Eq{"m.module_path": modulePath}).
-		Where("NOT m.incompatible").
-		Where(squirrel.Eq{"m.version_type": "release"})
+		Where(squirrel.Eq{"m.module_path": modulePath})
 }
 
 func collectSymbolHistory(check func(sh *internal.SymbolHistory, sm internal.SymbolMeta, v string, build internal.BuildContext) error) (*internal.SymbolHistory, func(rows *sql.Rows) error) {
diff --git a/internal/testing/fakedatasource/fakedatasource.go b/internal/testing/fakedatasource/fakedatasource.go
index 82212163..b44212a0 100644
--- a/internal/testing/fakedatasource/fakedatasource.go
+++ b/internal/testing/fakedatasource/fakedatasource.go
@@ -337,6 +337,34 @@ func (ds *FakeDataSource) GetModulePackages(ctx context.Context, modulePath, ver
 	return pkgs, nil
 }
 
+// GetSymbols returns symbols for the given unit and build context.
+func (ds *FakeDataSource) GetSymbols(ctx context.Context, pkgPath, modulePath, version string, bc internal.BuildContext) ([]*internal.Symbol, error) {
+	m := ds.getModule(modulePath, version)
+	if m == nil {
+		return nil, derrors.NotFound
+	}
+	u := findUnit(m, pkgPath)
+	if u == nil {
+		return nil, derrors.NotFound
+	}
+
+	var bcs []internal.BuildContext
+	for b := range u.Symbols {
+		if bc.Match(b) {
+			bcs = append(bcs, b)
+		}
+	}
+	if len(bcs) == 0 {
+		return nil, derrors.NotFound
+	}
+
+	sort.Slice(bcs, func(i, j int) bool {
+		return internal.CompareBuildContexts(bcs[i], bcs[j]) < 0
+	})
+
+	return u.Symbols[bcs[0]], nil
+}
+
 // SearchSupport reports the search types supported by this datasource.
 func (ds *FakeDataSource) SearchSupport() internal.SearchSupport {
 	// internal/frontend.TestDetermineSearchAction depends on us returning FullSearch