kythe/proto/serving.proto - platform/external/kythe - Git at Google

 /*
  * 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.serving;

 option go_package = "serving_go_proto";
 option java_package = "com.google.devtools.kythe.proto";

 import "kythe/proto/common.proto";

 // A derivative of xref.NodeInfo for serving.
 message Node {
   string ticket = 1;
   repeated kythe.proto.common.Fact fact = 2;

   // This node's definition location (anchor).
   ExpandedAnchor definition_location = 3;
 }

 // Full representation of a Kythe edge; useful during post-processing.
 message Edge {
   Node source = 1;
   string kind = 2;
   int32 ordinal = 5;
   Node target = 3;

   repeated kythe.proto.common.Fact fact = 4;
 }

 // An EdgeGroup represents a set of edges with the same kind and source.
 //
 // Note: this is a derivative of xref.EdgeSet_Group
 message EdgeGroup {
   message Edge {
     Node target = 1;
     int32 ordinal = 2;
   }
   string kind = 1;
   repeated Edge edge = 2;
 }

 // PagedEdgeSets are used for efficiently storing EdgeSets, all originating from
 // the same source ticket, in order to handle pagination requests.
 message PagedEdgeSet {
   // The source node for all the edges in the edge set.
   Node source = 1;

   // Each group is a collection of outbound edges from source node sharing a
   // given kind.
   repeated EdgeGroup group = 2;

   // Total number of edges in all of the EdgePages, including this one.
   int32 total_edges = 3 [deprecated = true];

   // Page indices for other EdgePages, sorted by edge kind.
   repeated PageIndex page_index = 4;
 }

 // PageIndex is a pointer to an EdgePage.  In order to keep the PagedEdgeSet
 // small, we don't store edges here.  We just store a key for looking up an
 // EdgePage and the type of edge.
 message PageIndex {
   // The kind of all edges on the referred EdgePage.
   string edge_kind = 1;

   // Total number of edges on the referred EdgePage.
   int32 edge_count = 2;

   // Key that can be used to lookup the referred EdgePage.
   string page_key = 3;
 }

 // EdgePages are a group of edges for a particular edge kind and source ticket.
 message EdgePage {
   // Corresponding PageIndex key that can be used to lookup this page.
   string page_key = 1;
   string source_ticket = 2;
   EdgeGroup edges_group = 3;
 }

 // FileDirectory describes a virtual directory of file nodes.
 message FileDirectory {
   // Each known entry in the directory.
   repeated Entry entry = 3;

   message Entry {
     // The kind of entry.
     Kind kind = 1;

     // The basename of the entry within the directory.
     string name = 2;

     // Set of known build configurations of this FILE or all files recursively
     // contained in/below this DIRECTORY.
     repeated string build_config = 3;
   }
   enum Kind {
     UNKNOWN = 0;
     FILE = 1;
     DIRECTORY = 2;
   }

   // Set of URIs for each contained sub-directory's corpus, root, and full path.
   repeated string subdirectory = 1 [deprecated = true];
   // Set of file node tickets contained within this directory.
   repeated string file_ticket = 2 [deprecated = true];
 }

 // CorpusRoots describes all of the known corpus/root pairs that contain file
 // nodes.
 message CorpusRoots {
   message Corpus {
     string corpus = 1;
     repeated string root = 2;
     repeated string build_config = 3;
   }
   repeated Corpus corpus = 1;
 }

 // A File is a specialized Node structure for file nodes.
 message File {
   string ticket = 1;
   bytes text = 2;
   string encoding = 3;
 }

 // A RawAnchor is a specialized Node structure for anchor nodes.
 message RawAnchor {
   string ticket = 1;
   int32 start_offset = 2;
   int32 end_offset = 3;

   int32 snippet_start = 4;
   int32 snippet_end = 5;

   string build_configuration = 6;
 }

 // ExpandedAnchors are constructed from an RawAnchor and its associated File.
 // They contain normalized Spans based on their parent file's text as well as
 // the UTF8-encoded text for both the anchor's span and its snippet span.
 message ExpandedAnchor {
   string ticket = 1;
   string kind = 2;
   reserved 3;

   string text = 4;
   kythe.proto.common.Span span = 5;

   string snippet = 6;
   kythe.proto.common.Span snippet_span = 7;

   string build_configuration = 8;
 }

 // FileDecorations stores a file's contents and all contained anchor edges.
 message FileDecorations {
   File file = 1;

   // Represents an edge from an anchor contained within the file to some target.
   message Decoration {
     RawAnchor anchor = 1;
     string kind = 2;
     string target = 5;

     string target_definition = 4;
     string semantic_scope = 6;
   }

   // The decorations located in the file, sorted by starting offset.
   repeated Decoration decoration = 2;

   // Set of nodes associated with each Decoration.target and
   // target_override.overridden.
   repeated Node target = 4;

   // Set of definition locations for each Decoration.target and
   // target_override.overridden.
   repeated ExpandedAnchor target_definitions = 3;

   // An overrides/extends for a defining Decoration's target.
   //
   // Example:
   //   overriding:  "kythe:#java.lang.String"
   //   kind:        EXTENDS
   //   overridden:  "kythe:#java.lang.Object"
   message Override {
     // What kind of override this is.
     enum Kind {
       OVERRIDES = 0;
       EXTENDS = 1;
     }

     // Ticket of overriding node (i.e. a Decoration target for a definition)
     string overriding = 1;
     // Ticket of node that is being overridden/extended.
     string overridden = 2;
     string overridden_definition = 5;

     Kind kind = 3;

     // MarkedSource for the node being overridden/extended (i.e. node whose
     // ticket is overridden).
     kythe.proto.common.MarkedSource marked_source = 4;
   }

   // List of overrides for target semantic nodes.
   repeated Override target_override = 5;

   // List of file diagnostics.
   repeated kythe.proto.common.Diagnostic diagnostic = 6;
 }

 // PagedCrossReferences are used for efficiently storing pre-cached data for
 // CrossReferencesReply.{definition,reference,caller} anchors and related
 // nodes.
 message PagedCrossReferences {
   reserved 10;

   // Nodes with cross-references that should be merged into this node's set of
   // cross-references.  These are highly related nodes that share a definition.
   repeated string merge_with = 7;

   // Node which is related to the source_ticket node.  The relation kind is
   // stored in each Group.  See: kythe.proto.CrossReferencesReply.RelatedNode.
   message RelatedNode {
     Node node = 1;
     int32 ordinal = 2;
   }

   // Caller of the source node with all associated callsites within the caller.
   message Caller {
     // The anchor covering the caller.
     ExpandedAnchor caller = 1;

     // The relevant semantic ticket for the caller.
     string semantic_caller = 2;
     // MarkedSource for the caller.
     kythe.proto.common.MarkedSource marked_source = 3;

     // Specific locations within the caller that caused the relationship to
     // exist.
     repeated ExpandedAnchor callsite = 4;
   }

   message Group {
     string kind = 1;

     // Build configuration for all anchors contained within the group.
     string build_config = 5;

     // A group is composed entirely of anchors, related nodes, or callers.
     repeated ExpandedAnchor anchor = 2;
     repeated RelatedNode related_node = 3;
     repeated Caller caller = 4;
   }

   message Page {
     string page_key = 1;
     string source_ticket = 2;
     Group group = 3;
   }

   // A PageIndex is a reference to a Page.
   message PageIndex {
     string kind = 1;
     int32 count = 2;
     string page_key = 3;
     string build_config = 4;
   }

   string source_ticket = 1;
   Node source_node = 8;
   repeated Group group = 2;
   repeated PageIndex page_index = 3;
   int32 total_references = 4 [deprecated = true];

   // Whether the source node is incomplete.  This changes whether
   // /kythe/edge/defines edges are considered declarations or definitions.
   // /kythe/edge/completes edges are always grouped as definitions.
   bool incomplete = 5;

   // The source node's MarkedSource.
   kythe.proto.common.MarkedSource marked_source = 6;
 }

 // A single node's documentation for the xrefs Documentation API.
 message Document {
   string ticket = 1;

   // The node's MarkedSource.
   kythe.proto.common.MarkedSource marked_source = 2;

   // 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 = 3;

   // Annotations for spans in raw_text. The ith Link corresponds to the span
   // starting at the ith [.
   repeated kythe.proto.common.Link link = 4;

   // Tickets for this document node's immediate children.
   repeated string child_ticket = 5;

   // Nodes referenced by documentation Links.
   repeated Node node = 6;

   // If non-empty, this is the ticket of a node whose documentation should
   // subsume this node's documentation.
   string documented_by = 7;
 }

 // A single identifier's information for the Identifier API
 message IdentifierMatch {
   message Node {
     // Kythe ticket for the matched node.
     string ticket = 1;

     // Kind of the node being referenced.
     string node_kind = 2;

     // Subkind of the node being referenced.
     string node_subkind = 3;
   }

   // The fully qualified identifier for the node.
   string qualified_name = 1;

   // The local identifier for the node.
   string base_name = 2;
   repeated Node node = 3;
 }

 // Relatives stores the nodes connected to a reference node via childOf edges:
 // "parents" (nodes that the reference node is a childOf)
 // or "children" (nodes that are each a childOf of the reference node).
 // Used by ExploreService for the Parents and Children APIs.
 message Relatives {
   enum Type {
     UNKNOWN = 0;   // never a valid value
     PARENTS = 1;   // the reference node is a childOf each element of 'tickets'
     CHILDREN = 2;  // each element of 'tickets' is a childOf the reference node
   }

   // Nodes connected to a reference node via childOf edges.
   repeated string tickets = 1;

   Type type = 2;
 }

 // Callgraph stores the tickets for semantic nodes of functions that call, or
 // are called by, a reference function semantic node.
 // Used by ExploreService for the Caller and Callee APIs.
 message Callgraph {
   enum Type {
     UNKNOWN = 0;  // never a valid value
     CALLER = 1;   // each element of 'tickets' is a caller of the reference node
     CALLEE = 2;   // each element of 'tickets' is called by the reference node
   }

   // Nodes connected to a reference node via the call relationship.
   repeated string tickets = 1;

   Type type = 2;
 }
	/*
	* 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.serving;

	option go_package = "serving_go_proto";
	option java_package = "com.google.devtools.kythe.proto";

	import "kythe/proto/common.proto";

	// A derivative of xref.NodeInfo for serving.
	message Node {
	string ticket = 1;
	repeated kythe.proto.common.Fact fact = 2;

	// This node's definition location (anchor).
	ExpandedAnchor definition_location = 3;
	}

	// Full representation of a Kythe edge; useful during post-processing.
	message Edge {
	Node source = 1;
	string kind = 2;
	int32 ordinal = 5;
	Node target = 3;

	repeated kythe.proto.common.Fact fact = 4;
	}

	// An EdgeGroup represents a set of edges with the same kind and source.
	//
	// Note: this is a derivative of xref.EdgeSet_Group
	message EdgeGroup {
	message Edge {
	Node target = 1;
	int32 ordinal = 2;
	}
	string kind = 1;
	repeated Edge edge = 2;
	}

	// PagedEdgeSets are used for efficiently storing EdgeSets, all originating from
	// the same source ticket, in order to handle pagination requests.
	message PagedEdgeSet {
	// The source node for all the edges in the edge set.
	Node source = 1;

	// Each group is a collection of outbound edges from source node sharing a
	// given kind.
	repeated EdgeGroup group = 2;

	// Total number of edges in all of the EdgePages, including this one.
	int32 total_edges = 3 [deprecated = true];

	// Page indices for other EdgePages, sorted by edge kind.
	repeated PageIndex page_index = 4;
	}

	// PageIndex is a pointer to an EdgePage. In order to keep the PagedEdgeSet
	// small, we don't store edges here. We just store a key for looking up an
	// EdgePage and the type of edge.
	message PageIndex {
	// The kind of all edges on the referred EdgePage.
	string edge_kind = 1;

	// Total number of edges on the referred EdgePage.
	int32 edge_count = 2;

	// Key that can be used to lookup the referred EdgePage.
	string page_key = 3;
	}

	// EdgePages are a group of edges for a particular edge kind and source ticket.
	message EdgePage {
	// Corresponding PageIndex key that can be used to lookup this page.
	string page_key = 1;
	string source_ticket = 2;
	EdgeGroup edges_group = 3;
	}

	// FileDirectory describes a virtual directory of file nodes.
	message FileDirectory {
	// Each known entry in the directory.
	repeated Entry entry = 3;

	message Entry {
	// The kind of entry.
	Kind kind = 1;

	// The basename of the entry within the directory.
	string name = 2;

	// Set of known build configurations of this FILE or all files recursively
	// contained in/below this DIRECTORY.
	repeated string build_config = 3;
	}
	enum Kind {
	UNKNOWN = 0;
	FILE = 1;
	DIRECTORY = 2;
	}

	// Set of URIs for each contained sub-directory's corpus, root, and full path.
	repeated string subdirectory = 1 [deprecated = true];
	// Set of file node tickets contained within this directory.
	repeated string file_ticket = 2 [deprecated = true];
	}

	// CorpusRoots describes all of the known corpus/root pairs that contain file
	// nodes.
	message CorpusRoots {
	message Corpus {
	string corpus = 1;
	repeated string root = 2;
	repeated string build_config = 3;
	}
	repeated Corpus corpus = 1;
	}

	// A File is a specialized Node structure for file nodes.
	message File {
	string ticket = 1;
	bytes text = 2;
	string encoding = 3;
	}

	// A RawAnchor is a specialized Node structure for anchor nodes.
	message RawAnchor {
	string ticket = 1;
	int32 start_offset = 2;
	int32 end_offset = 3;

	int32 snippet_start = 4;
	int32 snippet_end = 5;

	string build_configuration = 6;
	}

	// ExpandedAnchors are constructed from an RawAnchor and its associated File.
	// They contain normalized Spans based on their parent file's text as well as
	// the UTF8-encoded text for both the anchor's span and its snippet span.
	message ExpandedAnchor {
	string ticket = 1;
	string kind = 2;
	reserved 3;

	string text = 4;
	kythe.proto.common.Span span = 5;

	string snippet = 6;
	kythe.proto.common.Span snippet_span = 7;

	string build_configuration = 8;
	}

	// FileDecorations stores a file's contents and all contained anchor edges.
	message FileDecorations {
	File file = 1;

	// Represents an edge from an anchor contained within the file to some target.
	message Decoration {
	RawAnchor anchor = 1;
	string kind = 2;
	string target = 5;

	string target_definition = 4;
	string semantic_scope = 6;
	}

	// The decorations located in the file, sorted by starting offset.
	repeated Decoration decoration = 2;

	// Set of nodes associated with each Decoration.target and
	// target_override.overridden.
	repeated Node target = 4;

	// Set of definition locations for each Decoration.target and
	// target_override.overridden.
	repeated ExpandedAnchor target_definitions = 3;

	// An overrides/extends for a defining Decoration's target.
	//
	// Example:
	// overriding: "kythe:#java.lang.String"
	// kind: EXTENDS
	// overridden: "kythe:#java.lang.Object"
	message Override {
	// What kind of override this is.
	enum Kind {
	OVERRIDES = 0;
	EXTENDS = 1;
	}

	// Ticket of overriding node (i.e. a Decoration target for a definition)
	string overriding = 1;
	// Ticket of node that is being overridden/extended.
	string overridden = 2;
	string overridden_definition = 5;

	Kind kind = 3;

	// MarkedSource for the node being overridden/extended (i.e. node whose
	// ticket is overridden).
	kythe.proto.common.MarkedSource marked_source = 4;
	}

	// List of overrides for target semantic nodes.
	repeated Override target_override = 5;

	// List of file diagnostics.
	repeated kythe.proto.common.Diagnostic diagnostic = 6;
	}

	// PagedCrossReferences are used for efficiently storing pre-cached data for
	// CrossReferencesReply.{definition,reference,caller} anchors and related
	// nodes.
	message PagedCrossReferences {
	reserved 10;

	// Nodes with cross-references that should be merged into this node's set of
	// cross-references. These are highly related nodes that share a definition.
	repeated string merge_with = 7;

	// Node which is related to the source_ticket node. The relation kind is
	// stored in each Group. See: kythe.proto.CrossReferencesReply.RelatedNode.
	message RelatedNode {
	Node node = 1;
	int32 ordinal = 2;
	}

	// Caller of the source node with all associated callsites within the caller.
	message Caller {
	// The anchor covering the caller.
	ExpandedAnchor caller = 1;

	// The relevant semantic ticket for the caller.
	string semantic_caller = 2;
	// MarkedSource for the caller.
	kythe.proto.common.MarkedSource marked_source = 3;

	// Specific locations within the caller that caused the relationship to
	// exist.
	repeated ExpandedAnchor callsite = 4;
	}

	message Group {
	string kind = 1;

	// Build configuration for all anchors contained within the group.
	string build_config = 5;

	// A group is composed entirely of anchors, related nodes, or callers.
	repeated ExpandedAnchor anchor = 2;
	repeated RelatedNode related_node = 3;
	repeated Caller caller = 4;
	}

	message Page {
	string page_key = 1;
	string source_ticket = 2;
	Group group = 3;
	}

	// A PageIndex is a reference to a Page.
	message PageIndex {
	string kind = 1;
	int32 count = 2;
	string page_key = 3;
	string build_config = 4;
	}

	string source_ticket = 1;
	Node source_node = 8;
	repeated Group group = 2;
	repeated PageIndex page_index = 3;
	int32 total_references = 4 [deprecated = true];

	// Whether the source node is incomplete. This changes whether
	// /kythe/edge/defines edges are considered declarations or definitions.
	// /kythe/edge/completes edges are always grouped as definitions.
	bool incomplete = 5;

	// The source node's MarkedSource.
	kythe.proto.common.MarkedSource marked_source = 6;
	}

	// A single node's documentation for the xrefs Documentation API.
	message Document {
	string ticket = 1;

	// The node's MarkedSource.
	kythe.proto.common.MarkedSource marked_source = 2;

	// 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 = 3;

	// Annotations for spans in raw_text. The ith Link corresponds to the span
	// starting at the ith [.
	repeated kythe.proto.common.Link link = 4;

	// Tickets for this document node's immediate children.
	repeated string child_ticket = 5;

	// Nodes referenced by documentation Links.
	repeated Node node = 6;

	// If non-empty, this is the ticket of a node whose documentation should
	// subsume this node's documentation.
	string documented_by = 7;
	}

	// A single identifier's information for the Identifier API
	message IdentifierMatch {
	message Node {
	// Kythe ticket for the matched node.
	string ticket = 1;

	// Kind of the node being referenced.
	string node_kind = 2;

	// Subkind of the node being referenced.
	string node_subkind = 3;
	}

	// The fully qualified identifier for the node.
	string qualified_name = 1;

	// The local identifier for the node.
	string base_name = 2;
	repeated Node node = 3;
	}

	// Relatives stores the nodes connected to a reference node via childOf edges:
	// "parents" (nodes that the reference node is a childOf)
	// or "children" (nodes that are each a childOf of the reference node).
	// Used by ExploreService for the Parents and Children APIs.
	message Relatives {
	enum Type {
	UNKNOWN = 0; // never a valid value
	PARENTS = 1; // the reference node is a childOf each element of 'tickets'
	CHILDREN = 2; // each element of 'tickets' is a childOf the reference node
	}

	// Nodes connected to a reference node via childOf edges.
	repeated string tickets = 1;

	Type type = 2;
	}

	// Callgraph stores the tickets for semantic nodes of functions that call, or
	// are called by, a reference function semantic node.
	// Used by ExploreService for the Caller and Callee APIs.
	message Callgraph {
	enum Type {
	UNKNOWN = 0; // never a valid value
	CALLER = 1; // each element of 'tickets' is a caller of the reference node
	CALLEE = 2; // each element of 'tickets' is called by the reference node
	}

	// Nodes connected to a reference node via the call relationship.
	repeated string tickets = 1;

	Type type = 2;
	}