sourcegraph/cmd/frontend/graphqlbackend/codeintel.codenav.graphql

extend interface TreeEntry {
    """
    LSIF data for this tree entry.
    """
    lsif(
        """
        An optional filter for the name of the tool that produced the upload data.
        """
        toolName: String
    ): TreeEntryLSIFData
}

extend type GitTree {
    """
    LSIF data for this tree entry.
    """
    lsif(
        """
        An optional filter for the name of the tool that produced the upload data.
        """
        toolName: String
    ): GitTreeLSIFData
}

extend type GitBlob {
    """
    A wrapper around LSIF query methods. If no LSIF upload can be used to answer code
    intelligence queries for this path-at-revision, this resolves to null.
    """
    lsif(
        """
        An optional filter for the name of the tool that produced the upload data.
        """
        toolName: String
    ): GitBlobLSIFData

    """
    Provides code intelligence within the file.

    Experimental: This API is likely to change in the future.
    """
    localCodeIntel: JSONValue

    """
    A wrapper around syntactic hover and definition query methods.

    Experimental: This API is likely to change in the future.
    """
    symbolInfo(line: Int!, character: Int!): SymbolInfo

    """
    Return the code graph data associated with this blob.

    If there are multiple tools (i.e. name and version pairs) which
    have uploaded precise indexes for this blob, then this API will
    return multiple results even if
    filter == { provenance: { equals: Precise } }.

    Commit matching is done based on graph order.
    For merge commits or their children, it is possible that the
    same blob may have code graph data at different ancestors,
    in which case this API will return multiple results.

    EXPERIMENTAL: This API may change in the future.
    """
    codeGraphData(filter: CodeGraphDataFilter): [CodeGraphData!]
}

"""
EXPERIMENTAL: This type may change in a backwards-incompatible way.
"""
input CodeGraphDataFilter {
    """
    If this field is not set, then the codeGraphData API
    will go through each provenance each provenance one by one
    in the order Precise -> Syntactic -> SearchBased
    and stop when some data is available.
    """
    provenance: CodeGraphDataProvenanceComparator
}

"""
EXPERIMENTAL: This type may change in a backwards-incompatible way.
"""
input CodeGraphDataProvenanceComparator {
    """
    Checks for exact equality.
    """
    equals: CodeGraphDataProvenance
}

"""
EXPERIMENTAL: This type may change in a backwards-incompatible way.

TODO(issue: GRAPH-614): 'commit' field should have type GitCommit
before stabilizing this API.
"""
type CodeGraphData {
    """
    Coarse description of the data source for this code graph data.
    """
    provenance: CodeGraphDataProvenance!

    """
    The commit associated with this code graph data.

    In general, this will be an ancestor of the commit at which code
    graph data was requested, as code graph data may not be available
    at the exact commit for the blob.
    """
    commit: String!

    """
    Information about the tool which generated this code graph data
    """
    toolInfo: CodeGraphToolInfo

    """
    Occurrences are guaranteed to be sorted by range. It is possible
    for there to be multiple occurrences for the same exact source range.
    """
    occurrences(first: Int, after: String): SCIPOccurrenceConnection
}

"""
Identifies the tool which generated some code graph data.
"""
type CodeGraphToolInfo {
    """
    The name of the tool, e.g. scip-java.
    """
    name: String
    """
    The version of the tool, e.g. v1.0.0 or some SHA.
    """
    version: String
}

"""
Connection type for a list of occurrences.
"""
type SCIPOccurrenceConnection {
    """
    List of occurrences within a given page.
    """
    nodes: [SCIPOccurrence!]!

    """
    Pagination information.
    """
    pageInfo: PageInfo!
}

"""
EXPERIMENTAL: This type may change in a backwards-incompatible way.
"""
enum CodeGraphDataProvenance {
    """
    Based on a compiler, a type-checker or a similar data source
    which doesn't have false positives.
    Generally, the results are specific to a particular build configuration,
    such as for a specific OS or CPU, which can matter for
    codebases having a large amount of platform-specific code.
    """
    PRECISE
    """
    Based on a data source that uses an abstract or concrete syntax
    tree, but without access to reliable type information.
    """
    SYNTACTIC
    """
    Based on a data source that only does textual analysis, say
    using regular expressions.
    """
    SEARCH_BASED
}

"""
Metadata for a given (repo, commit, path, range) tuple.

EXPERIMENTAL: This type may change in a backwards-incompatible way.
"""
type SCIPOccurrence {
    """
    Symbol name using syntax specified by the SCIP schema.
    https://github.com/sourcegraph/scip/blob/main/scip.proto#L147-L188
    """
    symbol: String
    """
    Source range associated with this occurrence.
    """
    range: Range!
    """
    Description of the role a symbol plays at a particular source range.

    The 'Definition' and 'Reference' roles are mutually exclusive (exactly
    one of those will be present in the array below).
    """
    roles: [SymbolRole!]
    # We can add diagnostics etc. here in the future if needed.
}

"""
EXPERIMENTAL: This type may change in a backwards-compatible way.
"""
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.).
    """
    FORWARD_DEFINITION
}

"""
LSIF data available for a tree entry (file OR directory, see GitBlobLSIFData for file-specific
resolvers and GitTreeLSIFData for directory-specific resolvers.)
"""
interface TreeEntryLSIFData {
    """
    Code diagnostics provided through LSIF.
    """
    diagnostics(first: Int): DiagnosticConnection!
}

"""
A wrapper object around LSIF query methods for a particular git-tree-at-revision. When this node is
null, no LSIF data is available for the git tree in question.
"""
type GitTreeLSIFData implements TreeEntryLSIFData {
    """
    Code diagnostics provided through LSIF.
    """
    diagnostics(first: Int): DiagnosticConnection!
}

"""
A wrapper object around LSIF query methods for a particular git-blob-at-revision. When this node is
null, no LSIF data is available for the git blob in question.
"""
type GitBlobLSIFData implements TreeEntryLSIFData {
    """
    Return a flat list of all ranges in the document that have code intelligence.
    """
    stencil: [Range!]!

    """
    Get aggregated local code intelligence for all ranges that fall in the window
    indicated by the given zero-based start (inclusive) and end (exclusive) lines.
    The associated data for each range is "local", in that the locations and hover
    must also be defined in the same index as the source range. To get cross-repository
    and cross-bundle results, you must query the definitions, references, and hovers
    of that range explicitly.
    """
    ranges(startLine: Int!, endLine: Int!): CodeIntelligenceRangeConnection

    """
    A list of definitions of the symbol under the given document position.
    """
    definitions(
        """
        The line on which the symbol occurs (zero-based, inclusive).
        """
        line: Int!

        """
        The character (not byte) of the start line on which the symbol occurs (zero-based, inclusive).
        """
        character: Int!

        """
        When specified, it filters references by filename.
        """
        filter: String
    ): LocationConnection!

    """
    A list of references of the symbol under the given document position.
    """
    references(
        """
        The line on which the symbol occurs (zero-based, inclusive).
        """
        line: Int!

        """
        The character (not byte) of the start line on which the symbol occurs (zero-based, inclusive).
        """
        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.
        """
        filter: String
    ): LocationConnection!

    """
    A list of implementations of the symbol under the given document position.
    """
    implementations(
        """
        The line on which the symbol occurs (zero-based, inclusive).
        """
        line: Int!

        """
        The character (not byte) of the start line on which the symbol occurs (zero-based, inclusive).
        """
        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 implementation by filename.
        """
        filter: String
    ): LocationConnection!

    """
    A list of prototypes of the symbol under the given document position.
    """
    prototypes(
        """
        The line on which the symbol occurs (zero-based, inclusive).
        """
        line: Int!

        """
        The character (not byte) of the start line on which the symbol occurs (zero-based, inclusive).
        """
        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 prototypes by filename.
        """
        filter: String
    ): LocationConnection!

    """
    The hover result of the symbol under the given document position.
    """
    hover(
        """
        The line on which the symbol occurs (zero-based, inclusive).
        """
        line: Int!

        """
        The character (not byte) of the start line on which the symbol occurs (zero-based, inclusive).
        """
        character: Int!
    ): Hover

    """
    Code diagnostics provided through LSIF.
    """
    diagnostics(first: Int): DiagnosticConnection!

    """
    The indexes that could provide precise code intelligence for the current blob.
    """
    visibleIndexes: [PreciseIndex!]

    """
    SCIP snapshot data (similar to the additional information from the `scip snapshot` command) for each SCIP Occurrence.
    """
    snapshot(indexID: ID!): [SnapshotData!]
}

"""
The SCIP snapshot decoration for a single SCIP Occurrence.
"""
type SnapshotData {
    """
    The byte offset in the document immediately after the line the occurrence is on.
    """
    offset: Int!
    """
    The formatted SCIP symbol string.
    """
    data: String!

    """
    Any additional lines of snapshot output such as relationships, documentation etc.
    """
    additional: [String!]
}

"""
Aggregate local code intelligence for all ranges that fall between a window of lines in a document.
"""
type CodeIntelligenceRangeConnection {
    """
    Aggregate local code intelligence grouped by range.
    """
    nodes: [CodeIntelligenceRange!]!
}

"""
Aggregate code intelligence for a particular range within a document.
"""
type CodeIntelligenceRange {
    """
    The range this code intelligence applies to.
    """
    range: Range!

    """
    A list of definitions of the symbol occurring within the range.
    """
    definitions: LocationConnection!

    """
    A list of references of the symbol occurring within the range.
    """
    references: LocationConnection!

    """
    A list of implementations of the symbol occurring within the range.
    """
    implementations: LocationConnection!

    """
    The hover result of the symbol occurring within the range.
    """
    hover: Hover
}

"""
Hover range and markdown content.
"""
type Hover {
    """
    A markdown string containing the contents of the hover.
    """
    markdown: Markdown!

    """
    The range to highlight.
    """
    range: Range!
}

"""
A list of diagnostics.
"""
type DiagnosticConnection {
    """
    A list of diagnostics.
    """
    nodes: [Diagnostic!]!

    """
    The total count of diagnostics (which may be larger than nodes.length if the connection is paginated).
    """
    totalCount: Int

    """
    Pagination information.
    """
    pageInfo: PageInfo!
}

"""
Represents a diagnostic, such as a compiler error or warning.
"""
type Diagnostic {
    """
    The location at which the message applies.
    """
    location: Location!

    """
    The diagnostic's severity.
    """
    severity: DiagnosticSeverity

    """
    The diagnostic's code as provided by the tool.
    """
    code: String

    """
    A human-readable string describing the source of this
    diagnostic, e.g. "typescript" or "super lint".
    """
    source: String

    """
    The diagnostic's message.
    """
    message: String
}

"""
Represents the severity level of a diagnostic.
"""
enum DiagnosticSeverity {
    ERROR
    WARNING
    INFORMATION
    HINT
}

"""
SymbolInfo contains hover and definition methods. It's returned by GitBlob.symbolInfo(line, character).
"""
type SymbolInfo {
    """
    The definition of the symbol.
    """
    definition: SymbolLocation

    """
    The hover for the symbol.
    """
    hover: String
}

"""
SymbolLocation is a single-line range within a repository. It's returned by SymbolInfo.definition.
"""
type SymbolLocation {
    """
    The repo.
    """
    repo: String!

    """
    The commit.
    """
    commit: String!

    """
    The path.
    """
    path: String!

    """
    The range.
    """
    range: LineRange

    """
    The line.
    """
    line: Int! @deprecated(reason: "use range.line instead")

    """
    The character.
    """
    character: Int! @deprecated(reason: "use range.character instead")

    """
    The length.
    """
    length: Int! @deprecated(reason: "use range.length instead")
}

"""
LineRange is a span within a line.
"""
type LineRange {
    """
    The line.
    """
    line: Int!

    """
    The character.
    """
    character: Int!

    """
    The length.
    """
    length: Int!
}