Address feedback abotu optionality, add comments, introduce doc API, more tweaks

Author: varungandhi-src

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(
         """
@@ -105,21 +204,6 @@ 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.
         """
@@ -128,6 +212,8 @@ 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(
         """
@@ -163,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(
         """
@@ -198,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(
         """
@@ -263,44 +353,114 @@ type GitBlobLSIFData implements TreeEntryLSIFData {
 }
 
 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: LookupSCIPSymbol,
         """
-        Non-optional due to implementation limitations
+        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,
-        first: Int,
-        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, 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 LookupSCIPSymbol {
+input SymbolComparator {
     name: SymbolNameComparator!
     provenance: ProvenanceComparator!
 }
 
-"""
-In the future, we may want to extend this to allow passing in a suffix or a "symbol pattern".
-"""
+# 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 {
-    eq: String
+    equals: String
 }
 
 input ProvenanceComparator {
-    eq: Provenance
+    equals: Provenance
 }
 
-type SCIPSymbol {
+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 non-optional due to implementation limitations.
+    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!
     """
@@ -310,28 +470,40 @@ input LookupRange {
     """
     Defaults to repo-wide search if the path is not specified.
 
-    This field is non-optional due to implementation limitations.
+    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
-    # 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?
 }
 
 input RepositoryFilter {
@@ -343,7 +515,7 @@ input PathFilter {
 }
 
 input StringComparator {
-    eq: String
+    equals: String
 }
 
 enum SymbolUsageKind {
@@ -358,8 +530,17 @@ type UsageConnection {
     pageInfo: PageInfo!
 }
 
+type UsageRange {
+    repo: String!
+    revision: String!
+    range: Range!
+}
+
 type Usage {
-    symbol: SCIPSymbol!
+    symbol: SymbolInformation!
+
+    range: UsageRange
+
     """
     NOTE: Do not pass
     TODO: For this blob, it is generally more useful to get +N/-N lines