Sketch of SCIP-based GraphQL API

cmd/frontend/graphqlbackend/codeintel.codenav.graphql

@@ -105,6 +105,21 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
         """
         character: 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
+        'LocationConnection.pageInfo.endCursor' that is returned.
+        """
+        after: String
+
+        """
+        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, it filters references by filename.
         """
@@ -118,12 +133,12 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
         """
         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
@@ -231,6 +246,19 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
         character: Int!
     ): Hover
 
+    """
+    Either one of 'symbol' or 'range' must be provided, but this isn't enforced at the GraphQL
+    layer due to the lack of support for input unions.
+    https://github.com/graphql/graphql-wg/blob/main/rfcs/InputUnion.md
+    """
+    usages(
+        symbol: LookupSCIPSymbol,
+        range: LookupRange,
+        filter: UsagesFilter,
+        first: Int,
+        after: String,
+    ): UsageConnection!
+
     """
     Code diagnostics provided through LSIF.
     """
@@ -247,6 +275,77 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
     snapshot(indexID: ID!): [SnapshotData!]
 }
 
+"""
+In the future, we may want to extend this to allow passing in a suffix or a "symbol pattern".
+"""
+input LookupSCIPSymbol {
+    name: String!
+    provenance: Provenance!
+}
+
+type SCIPSymbol {
+    name: String!
+    provenance: Provenance!
+}
+
+input LookupRange {
+    start: LookupPosition!
+    end: LookupPosition!
+}
+
+input LookupPosition {
+    line: Int!
+    character: Int!
+}
+
+input UsagesFilter {
+    and: [UsagesFilter!]
+    or: [UsagesFilter!]
+    not: UsagesFilter
+    # TODO: Can we be flexible here and allow patterns while still maintaining fast queries.
+    repository: String
+    path: String
+    kind: SymbolUsageKind
+    # TODO: Provide a way of controlling fallback behavior for indexes?
+    # Not super sure how that would work, given that for different repositories,
+    # the hashes will all be different?
+}
+
+enum SymbolUsageKind {
+    Definition,
+    Reference,
+    Implementation,
+    Super,
+}
+
+type UsageConnection {
+    nodes: [Usage!]!
+    pageInfo: PageInfo!
+}
+
+type Usage {
+    symbol: SCIPSymbol!
+    """
+    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.
 """

cmd/frontend/graphqlbackend/schema.graphql

@@ -6172,17 +6172,55 @@ type HighlightedFile {
     """
     html: String!
     """
-    Base64 encoded JSON payload of LSIF Typed with syntax highlighting data.
+    DEPRECATED: Base64 encoded JSON payload of SCIP with syntax highlighting data.
     """
     lsif: String!
     """
+    """
+    document: AssociatedSCIPDocument!
+    """
     A list of the desired line ranges. Each list is a list of lines, where each element is an HTML
     table row '<tr>...</tr>' string. This is useful if you only need to display specific subsets of
     the file.
     """
     lineRanges(ranges: [HighlightLineRange!]!): [[String!]!]!
 }
 
+enum Provenance {
+    Precise,
+    Syntactic,
+    SearchBased,
+}
+
+interface WithProvenance {
+    """
+    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!
+}
+
+type AssociatedSCIPDocument implements WithProvenance {
+    """
+    Base64 encoded SCIP payload.
+
+    After decoding, the resulting byte buffer can be parsed with
+    pre-generated bindings in the sourcegraph/scip repository or
+    manually generating bindings using
+    https://github.com/sourcegraph/scip/blob/main/scip.proto
+    """
+    data: String!
+    provenance: Provenance!
+    dataSource: String!
+}
+
 """
 A file match.
 """