Sketch of SCIP-based GraphQL API

cmd/frontend/graphqlbackend/codeintel.codenav.graphql

@@ -47,6 +47,103 @@ extend type GitBlob {
     Experimental: This API is likely to change in the future.
     """
     symbolInfo(line: Int!, character: Int!): SymbolInfo
+
+    """
+    If filter.provenance? is not provided, then the API will go through
+    each provenance one by one in the order Precise -> Syntactic -> SearchBased
+    and stop when some data is available.
+    """
+    codeGraphData(filter: CodeGraphDataFilter): CodeGraphData
+}
+
+input CodeGraphDataFilter {
+    provenance: ProvenanceComparator
+}
+
+"""
+Invariants:
+1. forall sym in symbols.
+     (sym.provenance, sym.dataSource) == (scipDocument.provenance, scipDocument.dataSource)
+"""
+# Implementation notes:
+# 1. For precise code nav, we already have a code for inferring
+#    'visible uploads' using the commit graph machinery -> infer best upload
+#    -> get document for that using the given path.
+# 2. Syntactic will be similar to precise
+# 3. Search-based -> return empty document/lists.
+#
+# Ref panel logic:
+# 1. Request code graph data, specifying 'filter' if needed.
+#    Either the scipDocument or occurrences is fine.
+# 2. When a hover is triggered, attempt to look up occurrence in document or list
+#    or some other lookup structure constructed from those.
+# 3a. If one matching occurrence is found, use symbolName + range to call
+#     usagesForSymbol
+# 3b. If zero matching occurrences are found, use only range to call usagesForSymbol.
+# 3c. If more than one matching occurrence is found, use some more complex logic
+#     to offer a symbol picker.
+#     - Problem: For a symbol picker, ideally you'd use SymbolInformation.display_name,
+#       which is stored on SymbolInformation. However, display_name is not supported
+#       today by most SCIP indexers. And we don't have any API for getting the detailed
+#       SCIP SymbolInformation for a bunch of occurrences.
+type CodeGraphData {
+    scipDocument: AssociatedSCIPDocument
+
+    """
+    List of symbols with definitions in this document.
+
+    Invariant:
+    forall sym in symbols.
+        exists occ in occurrences such that
+            sym.name == occ.symbolName && occ.roles.contains(Definition)
+    """
+    # TODO: Should this be paginated to gracefully handle large generated files?
+    symbols: [SymbolInformation!]
+
+    """
+    Occurrences are guaranteed to be sorted by range.
+    """
+    # TODO: Should this be paginated to gracefully handle large generated files?
+    occurrences(filter: OccurrencesFilter): [Occurrence!]
+}
+
+type Occurrence {
+    symbolName: String
+    range: Range!
+    roles: [SymbolRole!]
+    # We can add diagnostics etc. here in the future if needed.
+}
+
+input OccurrencesFilter {
+    rangeFilter: RangeFilter
+    rolesFilter: RolesFilter
+    # We can add a DiagnosticsFilter etc. here in the future if needed.
+}
+
+input RangeFilter {
+    """
+    Zero-based line number, inclusive.
+    """
+    startLine: Int
+    """
+    Zero-based line number, inclusive.
+    """
+    endLine: Int
+}
+
+input RolesFilter {
+    or: [RolesFilter!]
+    equals: SymbolRole
+}
+
+enum SymbolRole {
+    Definition,
+    Reference,
+    """
+    Applicable for forward declarations in languages with header files (C, C++ etc.)
+    as well as standalone signatures in languages with separate interface files (OCaml etc.).
+    """
+    ForwardDefinition,
 }
 
 """
@@ -93,6 +190,8 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
 
     """
     A list of definitions of the symbol under the given document position.
+
+    DEPRECATED: Use usagesForSymbol with a Definition filter instead.
     """
     definitions(
         """
@@ -113,17 +212,19 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
 
     """
     A list of references of the symbol under the given document position.
+
+    DEPRECATED: Use usagesForSymbol with a Reference filter instead.
     """
     references(
         """
         The line on which the symbol occurs (zero-based, inclusive).
         """
-        line: Int!
+        line: Int
 
         """
         The character (not byte) of the start line on which the symbol occurs (zero-based, inclusive).
         """
-        character: Int!
+        character: Int
 
         """
         When specified, indicates that this request should be paginated and
@@ -148,6 +249,8 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
 
     """
     A list of implementations of the symbol under the given document position.
+
+    DEPRECATED: Use usagesForSymbol with Implementations filter instead.
     """
     implementations(
         """
@@ -183,6 +286,8 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
 
     """
     A list of prototypes of the symbol under the given document position.
+
+    DEPRECATED: Use usagesForSymbol with a Supers filter instead.
     """
     prototypes(
         """
@@ -247,6 +352,216 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
     snapshot(indexID: ID!): [SnapshotData!]
 }
 
+extend type Query {
+    """
+    Identify usages for either a semantic symbol, or the symbol(s) implied
+    by a source range.
+
+    Ordering and uniqueness guarantees:
+    1. The usages returned will already be de-duplicated.
+    2. Results for a single file are contiguous.
+    3. Results for a single repository are contiguous.
+
+    Related: See `codeGraphData` on GitBlob.
+    """
+    usagesForSymbol(
+        """
+        Symbol to perform the lookup for.
+
+        If provided, then the start and end position in 'range' are optional.
+
+        If not provided, then the start and end position in 'range' must be set.
+        In that case, the results will be merged across all semantic symbols
+        in the source range specified by [start, end]
+        """
+        symbol: SymbolComparator,
+        """
+        Information about an existing source range for a usage of the symbol.
+
+        TODO: Specify behavior for various cases of overlap between LookupRange
+        and actual occurrence range.
+        """
+        range: LookupRange!,
+
+        filter: UsagesFilter,
+
+        """
+        When specified, indicates that this request should be paginated and
+        the first N results (relative to the cursor) should be returned. i.e.
+        how many results to return per page.
+        """
+        first: Int
+
+        """
+        When specified, indicates that this request should be paginated and
+        to fetch results starting at this cursor.
+        A future request can be made for more results by passing in the
+        'UsageConnection.pageInfo.endCursor' that is returned.
+        """
+        after: String
+    ): UsageConnection!
+}
+
+input SymbolComparator {
+    name: SymbolNameComparator!
+    provenance: ProvenanceComparator!
+}
+
+# Implementation note: In the future, we may want to extend this
+# to allow passing in a suffix or a "symbol pattern".
+# See https://github.com/sourcegraph/sourcegraph/issues/59957
+input SymbolNameComparator {
+    equals: String
+}
+
+input ProvenanceComparator {
+    equals: Provenance
+}
+
+type SymbolInformation implements WithProvenance {
+    """
+    Symbol name using syntax specified by the SCIP schema.
+    https://github.com/sourcegraph/scip/blob/main/scip.proto#L147-L188
+
+    This value will generally be used in conjunction with
+    the `usagesBySymbol` API.
+    """
+    name: String!
+    """
+    Hover documentation for the symbol, in Markdown format.
+
+    The caller must take care to escape any particular strings,
+    such as raw HTML, as necessary.
+
+    The value is null when the hover documentation is not found
+    by 'dataSource'.
+
+    The value is empty when `dataSource` is confident that there
+    is no appropriate hover documentation to display.
+    """
+    documentation: [String!]
+    """
+    Coarse-grained information about the data source.
+    """
+    provenance: Provenance!
+    """
+    Opaque fine-grained information describing the data source.
+
+    Provided only for debugging.
+
+    This field should be ignored when checking structural equality.
+    """
+    dataSource: String
+}
+
+input LookupRange {
+    """
+    Defaults to instance-wide search if the repo is not specified.
+
+    This field is necessary if LookupSymbol is a repository-local or
+    file-local symbol. It is mandatory for cross-repo symbols
+    due to implementation limitations.
+    """
+    repo: String!
+    """
+    Defaults to HEAD of the default branch if not specified.
+    """
+    revision: String
+    """
+    Defaults to repo-wide search if the path is not specified.
+
+    This field is necessary if LookupSymbol is a file-local symbol.
+    It is mandatory for repository-local and cross-repo symbols
+    due to implementation limitations.
+    """
+    path: String!
+    start: LookupPosition
+    end: LookupPosition
+}
+
+input LookupPosition {
+    """
+    Zero-based count of newline (\n or \r\n) characters before this position.
+    """
+    line: Int!
+    """
+    Zero-based UTF-16 code unit offset from preceding newline (\n or \r\n) character.
+    """
+    character: Int!
+}
+
+"""
+An empty filter allows all kinds of usages for all paths in all repositories.
+
+However, if the symbol used for lookup is a file-local symbol or a
+repository-local symbol, then usages will automatically be limited to the
+same file or same repository respectively.
+"""
+input UsagesFilter {
+    and: [UsagesFilter!]
+    or: [UsagesFilter!]
+    not: UsagesFilter
+    repository: RepositoryFilter
+    path: PathFilter
+    kind: SymbolUsageKind
+}
+
+input RepositoryFilter {
+    name: StringComparator!
+}
+
+input PathFilter {
+    name: StringComparator!
+}
+
+input StringComparator {
+    equals: String
+}
+
+enum SymbolUsageKind {
+    Definition,
+    Reference,
+    Implementation,
+    Super,
+}
+
+type UsageConnection {
+    nodes: [Usage!]!
+    pageInfo: PageInfo!
+}
+
+type UsageRange {
+    repo: String!
+    revision: String!
+    range: Range!
+}
+
+type Usage {
+    symbol: SymbolInformation!
+
+    range: UsageRange
+
+    """
+    NOTE: Do not pass
+    TODO: For this blob, it is generally more useful to get +N/-N lines
+    rather than having to pass a range internally for the contents since
+    the offsets from the start will not be known a-priori.
+    """
+    blob: GitBlob!
+    """
+    Instead of blob { content }, allows accessing a sub-span of the content
+    using relative coordinates from the range of this usage. If linesBefore
+    or linesAfter is negative or exceeds the number of available lines,
+    the value is interpreted as until the start/end of the file.
+    """
+    surroundingBlobContent(surroundingLines: SurroundingLines = {linesBefore: 0, linesAfter: 0}): String!
+}
+
+input SurroundingLines {
+    linesBefore: Int
+    linesAfter: Int
+}
+
 """
 The SCIP snapshot decoration for a single SCIP Occurrence.
 """