kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/proto/link.proto (about)

     1  /*
     2   * Copyright 2018 The Kythe Authors. All rights reserved.
     3   *
     4   * Licensed under the Apache License, Version 2.0 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *   http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  syntax = "proto3";
    18  
    19  package kythe.proto;
    20  
    21  import "kythe/proto/common.proto";
    22  
    23  option go_package = "kythe.io/kythe/proto/link_go_proto";
    24  option java_package = "com.google.devtools.kythe.proto";
    25  
    26  // A LinkService resolves "links" based on qualified names.  Given a qualified
    27  // name, resolution consists of finding the entities that define that name and
    28  // returning the locations of their definition sites. This permits a client to
    29  // record a durable reference to an object whose definition may move within a
    30  // source file or even across source files over time.
    31  //
    32  // Because the mapping between qualified names and definitions is not unique in
    33  // general, the service permits the client to specify various constraints on a
    34  // query. The client records the effective constraints along with the qualified
    35  // name, e.g., as query parameters.
    36  //
    37  // Qualified names use the same format and have the same constraints as in the
    38  // IdentifierService defined by identifier.proto. This concurrence is intended,
    39  // so that a link service can be implemented using the same underlying data.
    40  service LinkService {
    41    // Resolve returns the links matching the specified request.  The server is
    42    // permitted to limit the size of the result set in order to ensure fast
    43    // responses. The server will report an error if its limits are exceeded.
    44    rpc Resolve(LinkRequest) returns (LinkReply) {}
    45  }
    46  
    47  message LinkRequest {
    48    // The qualified identifier to look for.
    49    string identifier = 1;
    50    // Restrict lookup to these corpus labels (optional).
    51    repeated string corpus = 2;
    52    // Restrict lookup to these languages (optional).
    53    repeated string language = 3;
    54    // Restrict lookup to these node kinds (optional).
    55    repeated string node_kind = 4;
    56  
    57    // Select definition locations matching these constraints.
    58    //
    59    // A file matches a constraint if its root, path, and corpus match the
    60    // provided RE2 regular expressions.
    61    //
    62    // A file is selected iff some include constraint matches it, and no exclude
    63    // constraint matches it.
    64    //
    65    // If include is empty, all files are included.
    66    // If exclude is empty, no files are excluded.
    67    message Location {
    68      string path = 1;
    69      string root = 2;
    70      string corpus = 3;
    71    }
    72    repeated Location include = 5;
    73    repeated Location exclude = 6;
    74  
    75    // Select definition locations having this number of parameters, if set.
    76    message Params {
    77      int32 count = 1;
    78    }
    79    Params params = 7;
    80  
    81    // Select what kinds of definitions to request, which determines which file
    82    // spans are returned for matching locations.
    83    enum DefinitionKind {
    84      BINDING = 0;  // defines/binding: span encloses the binding identifier
    85      FULL = 1;     // defines only: span encloses the full definition
    86      ANY = 2;      // any definition
    87    }
    88    DefinitionKind definition_kind = 8;
    89  
    90    // Include info about semantic nodes defined at each matching location.
    91    bool include_nodes = 9;
    92  }
    93  
    94  // A Link represents a single location matched by a LinkRequest.
    95  message Link {
    96    // The file ticket corresponding to the definition.
    97    string file_ticket = 1;
    98  
    99    // The physical span bounded by the defining anchor.
   100    kythe.proto.common.Span span = 2;
   101  
   102    // The semantic nodes defined at this location.  This field is only populated
   103    // if include_nodes was true.
   104    message Node {
   105      string ticket = 1;
   106      string base_name = 2;
   107      string identifier = 3;
   108    }
   109    repeated Node nodes = 3;
   110  }
   111  
   112  message LinkReply {
   113    repeated Link links = 1;
   114  }