kythe/proto/common.proto

/*
 * Copyright 2015 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.common;

option go_package = "common_go_proto";
option java_package = "com.google.devtools.kythe.proto";
option java_multiple_files = true;

// Fact represents a single key/value fact from the graph.
message Fact {
  string name = 1;
  bytes value = 2;
}

// A Point represents a location within a file or buffer.
//
// If line_number ≤ 0, the line number and column offset are considered
// unknown and will be ignored.
//
// A point with line_number > 0 is said to be _normalized_ if it satisfies
// the constraint 0 ≤ column_offset ≤ bytelen(line_number); that is, if the
// column_offset is within the actual range of the corresponding line.  A
// point can be normalized by adjusting line_number and column_offset so that
// this constraint is satisfied.  This may be impossible if the column offset
// exceeds the bounds of the file.
message Point {
  // The offset in bytes from the beginning of the file.
  // Requires 0 ≤ byte_offset ≤ len(file).
  int32 byte_offset = 1;

  // The line number containing the point, 1-based.
  int32 line_number = 2;

  // The byte offset of the point within its line.
  int32 column_offset = 3;
}

// A Span represents an inclusive-exclusive range inside of a file or buffer.
message Span {
  Point start = 1;
  Point end = 2;
}

message NodeInfo {
  // The matching facts known for that node, a map from fact name to value.
  map<string, bytes> facts = 2;

  // If known and unambiguous, an anchor ticket for this node's definition
  // location.
  // Tickets are Kythe URIs (http://www.kythe.io/docs/kythe-uri-spec.html).
  string definition = 5;

  reserved 1;
  reserved "ticket";
}

message Diagnostic {
  // Text span to which the diagnostic applies.  If the span is unset, the
  // diagnostic refers to its entire parent context (i.e. the file to which it
  // is attached).
  Span span = 1;

  // Plain-text diagnostic message to be reported to users.
  string message = 2;

  // Optional details that further refine the diagnostic but need not be
  // reported to users immediately.  This field can be used to provide more
  // context for bug reports and may contain compiler/build errors.
  string details = 3;

  // Optional URL leading to more detailed information on this diagnostic.  This
  // may be documentation on a particular class of errors or a tracking issue
  // for prevalent errors.
  string context_url = 4;
}

// A Diagnostic resolved to include its associated file through a Kythe `tagged`
// graph edge.
message ResolvedDiagnostic {
  CorpusPath corpus_path = 1;
  Diagnostic diagnostic = 2;
}

// A file path rooted in a corpus.  This is a subset of a Kythe VName.
message CorpusPath {
  string corpus = 1;
  string root = 2;
  string path = 3;
}

message Link {
  // Semantic tickets for DEFINITION links.
  repeated string definition = 3;

  enum Kind {  // Will be deprecated.
    // This annotates a link to a ticket.
    DEFINITION = 0;
    // This span of text contains a list of items.
    LIST = 1;
    // This span of text is an item in a list.
    LIST_ITEM = 2;
    // This span of text is important.
    IMPORTANT = 999;
  }
  // The kind of this span.
  Kind kind = 2 [deprecated = true];

  reserved 1;
}

// Marked up, source code-like text.
message MarkedSource {
  enum Kind {
    // This node only contains other nodes and has no special semantics.
    BOX = 0;
    // This node dominates nodes that should be classified as types.
    TYPE = 1;
    // This node dominates nodes that should be classified as parameters.
    PARAMETER = 2;
    // This node dominates nodes that should be classified as identifiers.
    IDENTIFIER = 3;
    // This node dominates nodes that should be classified as context.
    CONTEXT = 4;
    // This node dominates nodes that should be classified as initializers.
    INITIALIZER = 5;
    // Substitute this node with a PARAMETER formed from the param edges from
    // the context node starting with `lookup_index`.
    PARAMETER_LOOKUP_BY_PARAM = 6;
    // Substitute this node with the marked source derived from the
    // `lookup_index`th param edge of the context node.
    LOOKUP_BY_PARAM = 7;
    // Substitute this node with a PARAMETER formed from the param edges from
    // the context node starting with `lookup_index`. Checks the context
    // node for a `param/default` fact and uses that to set the
    // first_default_child field.
    PARAMETER_LOOKUP_BY_PARAM_WITH_DEFAULTS = 8;
    // Substitute this node with the marked source derived from the typed edge
    // of the context node.
    LOOKUP_BY_TYPED = 9;
  }
  Kind kind = 1;
  // Nodes expect to be printed as:
  // pre_text + (child + post_child_text)* + post_text
  // where post_child_text is not included after the final child unless
  // add_final_list_token is asserted. post_child_text should never be
  // printed if there are no children.
  string pre_text = 2;
  repeated MarkedSource child = 3;
  string post_child_text = 4;
  string post_text = 5;
  uint32 lookup_index = 6;
  // The default_children_count children at the end of the child list should
  // be considered as "default" or uninteresting.
  uint32 default_children_count = 7;
  // `add_final_list_token` ensures that `post_child_text` will be
  // included after any nonempty list when that list is followed by additional
  // text.
  bool add_final_list_token = 10;
  // Annotations covering this subtree's full span.
  repeated Link link = 11;
}

// Contains symbol information for Kythe graph nodes.
message SymbolInfo {
  // The base un-qualified name for a node ("printf", "String")
  string base_name = 1;
  // The fully qualified name for a node ("printf", "java.lang.String")
  string qualified_name = 2;
}