| /* |
| * Copyright 2018 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 = "explore_go_proto"; |
| option java_package = "com.google.devtools.kythe.proto"; |
| option java_multiple_files = true; |
| |
| import "kythe/proto/common.proto"; |
| import "kythe/proto/storage.proto"; |
| import "kythe/proto/xref.proto"; |
| |
| // This file defines code graph exploration interfaces, based on Kythe data. |
| // Design doc: go/kythe-api-proposal |
| // |
| // Tickets are Kythe URIs (http://www.kythe.io/docs/kythe-uri-spec.html). |
| |
| // ExploreService provides read-only access to aspects of the Kythe code graph, |
| // such as type hierarchies, call graphs, function parameters, and |
| // parents/children relationships. Requests should generally take time |
| // proportional to the size of the response (in the absence of filtering, at |
| // least). |
| |
| // In cases where properties of a node are requested (e.g. callers of a |
| // function) for which there are no such (e.g., the function has no callers), |
| // the response will not include that node. |
| |
| // THIS API IS EXPERIMENTAL; IMPLEMENTATION IS IN PROGRESS, AND THE API AND |
| // IMPLEMENTATION ARE SUBJECT TO CHANGE. PLEASE DO NOT USE WITHOUT CONTACTING |
| // THE KYTHE TEAM (kythe-dev@googlegroups.com). |
| |
| service ExploreService { |
| // Returns the (recursive) callers of a specified function, as a directed |
| // graph. |
| // The Callers/Callees functions are distinct from XrefService.CrossReferences |
| // in that these functions capture the semantic relationships between methods, |
| // rather than the locations in the code base where a method is called. |
| rpc Callers(CallersRequest) returns (CallersReply) {} |
| |
| // Returns the (recursive) callees of a specified function (that is, what |
| // functions this function calls), as a directed graph. |
| rpc Callees(CalleesRequest) returns (CalleesReply) {} |
| |
| // Returns the parents of a specified node (for example, |
| // the file for a class, or the class for a function). |
| // Note that in some cases a node may have more than one parent. |
| rpc Parents(ParentsRequest) returns (ParentsReply) {} |
| |
| // Returns the children of a specified node (for example, |
| // the classes contained in a file, or the functions contained in a class). |
| rpc Children(ChildrenRequest) returns (ChildrenReply) {} |
| |
| // Returns the hierarchy (supertypes and subtypes, including implementations) |
| // of a specified type, as a directed acyclic graph. |
| // NOT YET IMPLEMENTED |
| rpc TypeHierarchy(TypeHierarchyRequest) returns (TypeHierarchyReply) {} |
| |
| // Returns the parameters of a specified function. |
| // NOT YET IMPLEMENTED |
| rpc Parameters(ParametersRequest) returns (ParametersReply) {} |
| } |
| |
| // Shared/utility messages |
| |
| message NodeData { |
| // the "node/[sub]kind" node facts |
| string kind = 1; |
| string subkind = 2; |
| |
| // the relevant locations in which this node is found |
| // TODO: do we want span-specific locations? |
| repeated Location locations = 3; |
| |
| // anchor ticket |
| string definition_anchor = 4; |
| |
| common.MarkedSource code = 5; |
| } |
| |
| // If the RPC request does not specify otherwise, successors and predecessors |
| // are both populated. |
| message GraphNode { |
| NodeData node_data = 1; |
| |
| // semantic tickets of nodes connected to this node by incoming edges |
| repeated string predecessors = 2; |
| |
| // semantic tickets of nodes connected to this node by outgoing edges |
| repeated string successors = 3; |
| } |
| |
| message Graph { |
| map<string, GraphNode> nodes = 1; // semantic ticket -> node/topology data |
| } |
| |
| // Imposes restrictions on the nodes returned for a query. |
| // An unset NodeFilter is interpreted as "no restrictions on nodes returned". |
| message NodeFilter { |
| // if set, only return nodes whose languages match any of these strings |
| // TODO: consider enabling VName-based filtering for nodes as well as files |
| repeated string included_languages = 1; |
| |
| // if set, only return nodes whose files match any of these VNames |
| // Only the parts of the VName that relate to files are relevant here: |
| // https://kythe.io/docs/schema/#_vname_conventions |
| // TODO: consider also supplying exclusion specs as well as inclusion |
| repeated VName included_files = 2; |
| } |
| |
| // Used where we need a collection of tickets (either because we need it for a |
| // map or to be able to distinguish between "unset" and "empty"). |
| // If a Tickets field is unset, that means that it has not been populated; |
| // if it is set but there are no tickets in the list, then there are no tickets |
| // of the designated variety in the containing message. |
| message Tickets { |
| repeated string tickets = 1; |
| } |
| |
| // Type hierarchy |
| // The type hierarchy is represented in the response as a graph, with the |
| // input ticket marked. The graph will be acyclic. |
| // node types: "record" (class), "interface" |
| // edge types: "extends", "satisfies" (any given response will likely only |
| // include one edge type unless the type hierarchy crosses a language |
| // boundary). |
| |
| message TypeHierarchyRequest { |
| string type_ticket = 1; |
| |
| NodeFilter node_filter = 2; |
| } |
| |
| // Edge types are implicit (see above) |
| message TypeHierarchyReply { |
| // same as type_ticket in request |
| string type_ticket = 1; |
| |
| Graph graph = 2; |
| } |
| |
| // Call graph |
| // These APIs are for capturing the graphs induced by the _semantic_ relations |
| // between calling/callable nodes (for example, the functions that call, or are |
| // called by, this function node). |
| // |
| // If you’re looking for a one-ply relationship between functions and the |
| // _locations_ in the code at which they are called, Kythe XRefService's |
| // CrossReferences API should do what you want. |
| |
| // Requests the incoming callgraphs for each of the specified nodes. |
| message CallersRequest { |
| repeated string tickets = 1; |
| } |
| |
| message CallersReply { |
| // Represents the call relationships to each of the input tickets, from |
| // all callers of those tickets, as a single graph. |
| Graph graph = 1; |
| } |
| |
| // Requests the outgoing callgraphs for each of the specified nodes. |
| message CalleesRequest { |
| repeated string tickets = 1; |
| } |
| |
| // TODO: consider merging this and CallersReply into a single message |
| // (CallgraphReply) unless we have reason to believe they need to be distinct |
| message CalleesReply { |
| // Represents the call relationships from each of the input tickets, to |
| // all callees of those tickets, as a single graph. |
| Graph graph = 1; |
| } |
| |
| // Function parameters |
| // node types: function |
| // edge types: TBD |
| |
| // Requests the parameters and return value of the specified function |
| message ParametersRequest { |
| repeated string function_tickets = 1; |
| } |
| |
| message ParametersReply { |
| map<string, Tickets> function_to_parameters = 1; |
| |
| map<string, string> function_to_return_value = 2; |
| |
| // data for functions and parameters |
| map<string, NodeData> node_data = 3; |
| } |
| |
| // Parents and children |
| // node types: package, record (class), interface, function, ... |
| // edge type: childof |
| |
| // * what package is this file/class/interface in? |
| // * what is the class/interface that this function is in? |
| |
| // Fetches the tickets for the enclosing contexts of the specified ticket |
| // (e.g.: what package is this file in? what class is this function in?). |
| message ParentsRequest { |
| repeated string tickets = 1; |
| } |
| |
| message ParentsReply { |
| // associates each input ticket with the set of tickets that contain it |
| map<string, Tickets> input_to_parents = 1; |
| } |
| |
| // Fetches the tickets for which the specified ticket is the enclosing context |
| // (e.g. what files are in this package? what functions are in this class?). |
| message ChildrenRequest { |
| repeated string tickets = 1; |
| } |
| |
| message ChildrenReply { |
| // associates each input ticket with the set of tickets contained by it |
| map<string, Tickets> input_to_children = 1; |
| } |