kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/proto/xref.proto

/*
 * Copyright 2014 The Kythe Authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";

package kythe.proto;

option go_package = "kythe.io/kythe/proto/xref_go_proto";
option java_package = "com.google.devtools.kythe.proto";
option java_multiple_files = true;

import "kythe/proto/common.proto";

// This file defines a cross-reference service interface, based on Kythe data.
//
// Tickets are Kythe URIs (http://www.kythe.io/docs/kythe-uri-spec.html).

// XRefService provides fast read-only access to Kythe cross-reference
// relationships.  "Cross-references" generally include non-transitive
// (single-step) relations like usage of a declaration, instantiation of a
// type, invocation of a function, direct inheritance or overrides, and so
// forth.  Some transitive relations can be converted into cross-references by
// precomputing a flattened representation of a transitive relation.
//
// Key design principles:
//  - All requests must be satisfied "quickly", e.g., in time proportional to
//    the size of the returned set.
//
//  - The client should be able to batch related requests.
//
//  - The client specifies exactly what facts should be returned.
//
service XRefService {
  // Decorations returns an index of the nodes and edges associated with a
  // particular file node.
  rpc Decorations(DecorationsRequest) returns (DecorationsReply) {}

  // CrossReferences returns the global references, definitions, declarations,
  // callers, and related nodes of a set of requested nodes.
  rpc CrossReferences(CrossReferencesRequest) returns (CrossReferencesReply) {}

  // Documentation takes a set of tickets for semantic objects and returns
  // documentation about them, including generated signatures and
  // user-provided text. The documentation may refer to tickets for other
  // nodes in the graph.
  rpc Documentation(DocumentationRequest) returns (DocumentationReply) {}
}

// A Location represents a single span of zero or more contiguous bytes of a
// file or buffer.  An empty LOCATION denotes the entirety of the referenced
// file or buffer.
//
message Location {
  // The ticket of the file this location belongs to.  If the location
  // represents a memory buffer, the ticket should be omitted.
  string ticket = 1;

  enum Kind {
    // The entire file; the start and end fields are ignored.
    FILE = 0;

    // The point or span of file subtended by start and end.
    SPAN = 1;
  }

  // What kind of location this is.
  Kind kind = 2;

  // If kind == SPAN, this is the represented span within the file.
  common.Span span = 5;

  // A location is _valid_ if 0 ≤ span.start.byte_offset ≤ span.end.byte_offset.
  // If a valid location has span.start.byte_offset = span.end.byte_offset, it
  // denotes a single point; otherwise it denotes the half-closed interval
  // [start.offset, end.offset).
  //
  // When kind = FILE, span should be unset or set to zero values.

  reserved 3, 4;
}

// Which types of snippets to return from a given CrossReferences or Decorations
// RPC.
// TODO(schroederc): extend snippet kinds to be (none, indexer-default, or
// always line-based) instead of (none, all).
enum SnippetsKind {
  // Return no snippets.
  NONE = 0;
  // Return the default snippet for each item that has one.
  DEFAULT = 1;
}

message DecorationsRequest {
  // The location of the file to fetch decorations for.  The ticket of location
  // must be non-empty.  It is an error in any case if location is invalid.
  Location location = 1;

  enum SpanKind {
    // If the location is a SPAN, only decorations contained within the
    // specified window of the file are returned.  This is the default behavior.
    WITHIN_SPAN = 0;

    // If the location is a SPAN, any decorations that surround it are returned.
    AROUND_SPAN = 1;
  }

  // How to treat SPAN locations.
  SpanKind span_kind = 10;

  // If dirty_buffer is non-empty, the results will be adjusted (patched) to
  // account for the regions of the specified file differing from the contents
  // of the dirty buffer.
  bytes dirty_buffer = 2;

  // If true, return the encoded source text for the selected window.  Source
  // text is not affected by patching.
  bool source_text = 3;

  // If true, return reference edges whose source nodes are located in the
  // selected window.  References are affected by patching.
  bool references = 4;

  // If true, return definition locations, if possible, for each returned
  // reference target in the DecorationsReply.
  bool target_definitions = 6;

  // A collection of filter globs that specify which facts (by name) should be
  // returned for each node.  If filter is empty or unset, no node facts are
  // returned.  The filter applies to ALL referenced nodes.  See EdgesRequest
  // (graph.proto) for the format of the filter globs.
  repeated string filter = 5;

  // If true, for every defines/binding Reference in the reply, a NodeInfo
  // will be provided for each node that Reference extends or overrides.
  // Furthermore, if definition_locations is true, the response's
  // definition_locations field will include (where possible) the locations of
  // the definitions of the nodes that are extended or overridden.
  bool extends_overrides = 7;

  // If true, return diagnostics for the given file.
  bool diagnostics = 8;

  // What kind of snippets to return (or none).
  SnippetsKind snippets = 9;

  // Set of build configurations with which to filter decorations.  If empty,
  // no filtering based on build configs will be done; all decorations for the
  // file will be returned.
  repeated string build_config = 11;

  // Whether to return known semantic scopes per Reference.
  bool semantic_scopes = 12;

  // The user's Workspace.  May be used as a target for patching spans to match
  // the current state of the referenced files.
  Workspace workspace = 13;

  // Whether to patch spans against the given Workspace.
  bool patch_against_workspace = 14;
}

// File represents a whole file
message File {
  kythe.proto.common.CorpusPath corpus_path = 1;

  string revision = 2;
}

message DecorationsReply {
  // The normalized location for which decorations are returned.
  Location location = 1;

  // The revision of the corpus containing this file's data.
  string revision = 18;

  // The encoded source text for the selected window.
  optional bytes source_text = 2;
  string encoding = 3;

  // Represents a reference edge source ---KIND---> target.  Each source is an
  // anchor within the requested source location.
  message Reference {
    string target_ticket = 2;
    string kind = 3;

    // Anchor ticket of the target's definition.  Populated only if
    // target_definitions is true in the DecorationsRequest and the target has
    // a single unambiguous definition.  For each ticket, an Anchor will be
    // populated in the top-level definition_locations map.
    string target_definition = 4;

    // The reference's span within the source file.
    common.Span span = 5;

    // The build config of the file containing this reference.
    string build_config = 6;

    // Ticket of the semantic node with the narrowest scope enclosing the
    // reference.  Populated only if semantic_scopes is true in the
    // DecorationsRequest.
    string semantic_scope = 7;

    // The revision of the file being targeted by this reference, may be empty
    // if targeting a non-file.
    string target_revision = 8;

    reserved 1, 10, 11;
  }

  message Override {
    // What kind of override this is.
    enum Kind {
      OVERRIDES = 0;
      EXTENDS = 1;
    }

    // The target of the override.
    string target = 1;
    // Anchor ticket of the override target's definition.  Populated only if
    // target_definitions is true in the DecorationsRequest and the target has
    // a single unambiguous definition.  For each ticket, an Anchor will be
    // populated in the top-level definition_locations map.
    string target_definition = 5;

    // The kind of override.
    Kind kind = 2;

    // A display name for the object at ticket.
    kythe.proto.common.MarkedSource marked_source = 4;

    reserved 3;
  }

  message Overrides {
    repeated Override override = 1;
  }

  // The reference edges located in the specified window. Sorted in the order
  // of their position in the file (first by start offset, then by end offset).
  repeated Reference reference = 4;

  // If requested, a list of diagnostics applying to the requested file
  // location.
  // TODO(schroederc): filter spanning diagnostics by build configuration
  repeated common.Diagnostic diagnostic = 5;

  // List of files that generate the requested file.
  repeated File generated_by_file = 19;

  // This field will contain one entry, keyed by ticket, for each distinct node
  // referenced by a reference edge that has at least 1 non-filtered fact.
  map<string, common.NodeInfo> nodes = 15;

  // Each anchor cited as a target definition in the references/overrides.  The
  // map is keyed by each anchor's ticket.
  map<string, Anchor> definition_locations = 16;

  // Maps from semantic nodes on the right-hand side of defines/binding
  // references to the list of their overrides.
  map<string, Overrides> extends_overrides = 17;

  // A unique identifier for the underlying dataset serving this reply.
  string build_id = 20;

  reserved 6;
}

message CrossReferencesRequest {
  // The tickets of nodes for which to return cross-references.
  // The server must report an error if this field is empty.
  // The server may limit the number of tickets per request to ensure an
  // efficient implementation.
  repeated string ticket = 1;

  enum DefinitionKind {
    // No definitions will be populated in the CrossReferencesReply.
    NO_DEFINITIONS = 0;

    // All known definition anchors reached by the "/kythe/edge/defines" edge
    // kind (or its variants) will be populated in the CrossReferencesReply.
    ALL_DEFINITIONS = 1;

    // Only definition anchors reached by the "/kythe/edge/defines" edge kind
    // will be populated in the CrossReferencesReply.
    FULL_DEFINITIONS = 2;

    // Only definition anchors reached by the "/kythe/edge/defines/binding" edge
    // kind will be populated in the CrossReferencesReply.
    BINDING_DEFINITIONS = 3;
  }

  // Determines what kind of definition anchors, if any, should be returned in
  // the response.  See the documentation for each DefinitionKind for more
  // information.
  DefinitionKind definition_kind = 2;

  enum DeclarationKind {
    // No declarations will be populated in the CrossDeclarationsReply.
    NO_DECLARATIONS = 0;
    // When the source node is incomplete, all known declaration anchors reached
    // by the "/kythe/edge/defines" edge kind (or its variants) will be
    // populated in the CrossDeclarationsReply.
    ALL_DECLARATIONS = 1;
  }

  // Determines what kind of declaration anchors, if any, should be returned in
  // the response.  See the documentation for each DeclarationKind for more
  // information.
  DeclarationKind declaration_kind = 7;

  enum ReferenceKind {
    // No references will be populated in the CrossReferencesReply.
    NO_REFERENCES = 0;
    // Only callgraph-related references as described in
    // http://www.kythe.io/docs/schema/callgraph.html
    CALL_REFERENCES = 1;
    // All references except those that are related to the callgraph.
    NON_CALL_REFERENCES = 2;
    // All known reference anchors reached by the "/kythe/edge/ref" edge kind
    // (or its variants) will be populated in the CrossReferencesReply.
    ALL_REFERENCES = 3;
  }

  // Determines what kind of reference anchors, if any, should be returned in
  // the response.  See the documentation for each ReferenceKind for more
  // information.
  ReferenceKind reference_kind = 3;

  enum CallerKind {
    // No callgraph information will be populated in the CrossReferencesReply.
    NO_CALLERS = 0;
    // Callgraph information will be populated in the CrossReferencesReply.
    DIRECT_CALLERS = 1;
    // Callgraph information will be populated in the CrossReferencesReply.
    // Calls to override-related functions will also be considered and each
    // RelatedAnchor will be marked as speculative.
    OVERRIDE_CALLERS = 2;
  }

  // Determines what kind of callgraph information, if any, should be returned
  // in the response.  See the documentation for each CallerKind for more
  // information.
  CallerKind caller_kind = 12;

  // Whether to include scopes for all references.  References with scopes will
  // appear as the sites of a RelatedAnchor with their semantic scope populating
  // the anchor/ticket/marked_source fields. If the serving data does not
  // provide a scope for a reference, the RelatedAnchor will have no sites and
  // the actual reference will be the primary anchor.
  bool semantic_scopes = 20;

  // Collection of filter globs that determines which facts will be returned for
  // the related nodes of each requested node.  If filter is empty or unset, no
  // node facts or related nodes are returned.  See EdgesRequest (graph.proto)
  // for the format of the filter globs.
  repeated string filter = 5;

  // Determines which relation kinds for RelatedNodes should be returned in the
  // response.  If empty, all known RelatedNodes will be returned that match the
  // above filter.  Otherwise, only RelatedNodes with one of these requested
  // relation kinds, and matching the above filter, will be returned in the
  // response.
  //
  // Importantly, this is not a list of node kinds; this is a list of edge kinds
  // (i.e. values for RelatedNode.relation_kind field).
  //
  // N.B.: When requesting related nodes, you must also set the filter,
  // otherwise no data will be returned for the relationships requested.
  repeated string related_node_kind = 14;

  // Determines whether each Anchor in the response should have its text field
  // populated.
  bool anchor_text = 6;

  // Determines whether each NodeInfo matching the above filters will have its
  // definition location populated (assuming it has one).
  bool node_definitions = 8;

  enum TotalsQuality {
    UNSPECIFIED_TOTALS = 0;
    PRECISE_TOTALS = 1;
    APPROXIMATE_TOTALS = 2;
  }
  // Quality of the aggregated xref totals returned for the requested tickets.
  // If PRECISE, the totals will be accurate across all requested tickets and
  // pages.  If APPROXIMATE, the totals may be partial/approximate so that the
  // server can return results as soon as possible.
  TotalsQuality totals_quality = 16;

  // The cross-references matching a request are organized into logical pages.
  // The size of each page is a number of distinct cross-references
  // (definitions, references, documentation, and related nodes).
  //
  // If page_token is empty, cross-references will be returned starting at the
  // beginning of the sequence; otherwise the starting point named by the
  // page_token will be used.  Legal values of page_token are returned by the
  // server in the next_page_token field of the CrossReferencesReply.  A page
  // token should be treated as an opaque value by the client, and is valid only
  // relative to a particular CrossReferencesRequest.  If an invalid page token
  // is requested, the server will return an error.
  //
  // If page_size > 0, at most that number of cross-references will be returned
  // by the service for this request (see ReferenceSet and CrossReferencesReply
  // below).  If page_size = 0, the default, the server will assume a reasonable
  // default page size.  The server will return an error if page_size < 0.
  //
  // The server is allowed to return fewer cross-references than the requested
  // page_size, even if more are available, save that it must return at least 1
  // edge if any are available at all.
  int32 page_size = 10;
  string page_token = 11;

  // What kind of snippets to return (or none).
  SnippetsKind snippets = 13;

  // Set of build configurations with which to filter xrefs.  If empty, no
  // filtering based on build configs will be done; all xrefs for the requested
  // nodes will be returned.
  repeated string build_config = 15;

  // The user's Workspace.  May be used as a target for patching spans to match
  // the current state of the referenced files.
  Workspace workspace = 17;

  // Whether to patch spans against the given Workspace.
  bool patch_against_workspace = 18;

  // Set of filters to apply to each xref's parent file.
  CorpusPathFilters corpus_path_filters = 19;

  reserved 4;
  reserved 100;
}

message CorpusPathFilters {
  repeated CorpusPathFilter filter = 1;
}

// A filter for CorpusPaths.  The filter matches if each component pattern
// matches (an empty pattern implies no filtering on that component).
message CorpusPathFilter {
  enum Type {
    DEFAULT = 0;
    INCLUDE_ONLY = 1;
    EXCLUDE = 2;
  }
  Type type = 1;

  // Corpus pattern to match against.
  string corpus = 2;
  // If true, only use filter if the corpus matches. If false, include corpus
  // in the normal pattern matching behavior for this filter.
  bool corpus_specific_filter = 6;
  // Root pattern to match against.
  string root = 3;
  // Path pattern to match against.
  string path = 4;

  // Fully resolved path pattern to match against.  The resolved path is
  // determined by the server implementation.
  string resolved_path = 5;
}

// TODO(schroederc): eliminate duplicate serving.ExpandedAnchor message
// defintion

message Anchor {
  // Ticket of the anchor node
  string ticket = 1;
  // Edge kind describing the anchor's relationship with its referenced node
  string kind = 2;

  // Parent ticket of the anchor; this is the file containing the anchor
  string parent = 3;

  // Span of the anchor within its parent's text
  common.Span span = 10;
  // The anchor's spanning text within the anchor parent's text
  string text = 6;

  // User-readable snippet of the anchor parent's text at the location of this
  // anchor
  string snippet = 7;
  // Span of the anchor's snippet within its parent's text
  common.Span snippet_span = 11;

  // The build config of the file containing this anchor.
  string build_config = 12;

  // The revision of the corpus containing this anchor's parent file data.
  string revision = 14;

  reserved 4, 5, 8, 9;
}

message Printable {
  // Raw text that can be displayed to the user (but may also contain
  // markup that can be interpreted, like Doxygen comments). Links are
  // marked using []. \ is an escape character (where possible escape
  // sequences are \[, \], and \\).
  string raw_text = 1;
  // Annotations for spans in raw_text. The ith Link corresponds to the span
  // starting at the ith [.
  repeated kythe.proto.common.Link link = 2;
}

message CrossReferencesReply {
  message RelatedNode {
    // Ticket of the node
    string ticket = 1;
    // Edge kind describing the node's relation
    string relation_kind = 2;
    // Optional ordinal for edges of the same relation_kind.
    int32 ordinal = 3;
  }

  message RelatedAnchor {
    // The anchor covering the related object.  The scope/caller of the sites.
    Anchor anchor = 1;
    // A name for the related object.
    kythe.proto.common.MarkedSource marked_source = 5;
    // Specific locations, usually within the related object, that caused
    // the relationship to exist. This field is relevant to caller sets and
    // scoped references.
    repeated Anchor site = 3;
    // The relevant semantic object. Populated for callers and scoped
    // references.
    string ticket = 4;

    // Whether the anchor, and its sites, are speculative and may not be precise
    // with respect to a program's execution.  Examples include callsites that
    // may occur through dynamic dispatch or ref/writes/thunk locations.
    bool speculative = 6;

    reserved 2;
  }

  message CrossReferenceSet {
    string ticket = 1;

    // A name for the given node.
    kythe.proto.common.MarkedSource marked_source = 8;

    // The set of definitions for the given node.
    repeated RelatedAnchor definition = 2;
    // The set of declarations for the given node.
    repeated RelatedAnchor declaration = 5;
    // The set of simple references for the given node.
    repeated RelatedAnchor reference = 3;
    // The set of callers for the given node.
    repeated RelatedAnchor caller = 6;

    // The set of related nodes to the given node.
    repeated RelatedNode related_node = 10;

    reserved 4, 7;
  }

  message Total {
    int64 definitions = 1;
    int64 declarations = 2;
    int64 references = 3 [deprecated = true];
    int64 documentation = 4;
    int64 callers = 5;

    // Map from ref edge type to count.
    //
    // Example
    // /kythe/edge/ref -> 20,
    // /kythe/edge/ref/writes -> 50
    map<string, int64> ref_edge_to_count = 7;
    map<string, int64> related_nodes_by_relation = 6;
  }
  // Total number of cross-references on all pages matching requested kinds,
  // build configs, and filters. This may be an approximation if allowed by the
  // CrossReferencesRequest.
  Total total = 5;

  // Total number of cross-references removed based on the request's
  // corpus_path_filters. This may be an approximation if allowed by the
  // CrossReferencesRequest.
  Total filtered = 12;

  // A map from ticket to cross-references for each ticket specified in the
  // request message.
  map<string, CrossReferenceSet> cross_references = 1;

  // A map from ticket to the facts provided based on the requested filters,
  // for each of the tickets provided in the request and their related nodes.
  map<string, common.NodeInfo> nodes = 2;

  // A map from the ticket of each definition mentioned in the nodes map, to
  // its corresponding anchor. This map is only populated if the request set
  // the node_definitions field true.
  map<string, Anchor> definition_locations = 3;

  // If there are additional pages of cross-references after the ones returned
  // in this reply, next_page_token is the page token that may be passed to
  // fetch the next page in sequence after this one.  If there are no further
  // cross-references, this field will be empty.
  string next_page_token = 10;

  // A unique identifier for the underlying dataset serving this reply.
  string build_id = 11;
}

message DocumentationRequest {
  // Semantic tickets about which documentation is sought.
  repeated string ticket = 1;

  // A collection of filter globs that specify which facts (by name) should be
  // returned for each node.  If filter is empty or unset, no node facts are
  // returned. The filter applies to ALL documented and linked nodes.
  // See EdgesRequest (graph.proto) for the format of the filter globs.
  repeated string filter = 2;

  // If set, this DocumentationRequest will return documents for the requested
  // tickets as well as their immediate semantic descendants.
  bool include_children = 3;

  // The user's Workspace.  May be used as a target for patching spans to match
  // the current state of the referenced files.
  Workspace workspace = 4;

  // Whether to patch spans against the given Workspace.
  bool patch_against_workspace = 5;
}

message DocumentationReply {
  message Document {
    // The ticket to which this Document refers.
    string ticket = 1;
    // Documentation that can be displayed to the user.
    Printable text = 2;
    // A structured summary of the (qualified) identity of the documented node.
    kythe.proto.common.MarkedSource marked_source = 8;

    // The children of this Document. This relationship may be distinct from
    // the `childof` relationship.
    repeated Document children = 9;

    reserved 3, 4, 5, 6, 7;
  }
  repeated Document document = 1;
  // The facts left from the requested filters of the documented node facts.
  map<string, common.NodeInfo> nodes = 2;
  // Map from the definition anchor tickets referred to in each NodeInfo to
  // their corresponding Anchor data.
  map<string, Anchor> definition_locations = 3;

  // A unique identifier for the underlying dataset serving this reply.
  string build_id = 4;
}

// A Workspace is a pointer to the root of a user's workspace.  This is
// typically the root of a source repository.
message Workspace {
  // The root of a user workspace encoded as a uri.  The uri format is dependent
  // on the capabilities of the server.
  string uri = 1;
}