kythe/proto/xref_serving.proto

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

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

import "kythe/proto/common.proto";
import "kythe/proto/schema.proto";
import "kythe/proto/serving.proto";
import "kythe/proto/storage.proto";

// Columnar protocol buffer format for FileDecorations.
//
// Design: https://github.com/kythe/kythe/blob/master/kythe/docs/rfc/2909.md
//
// Columnar key prefix: "fd"-file
message FileDecorations {
  kythe.proto.VName file = 1;

  oneof entry {
    Index index = 2;
    Text text = 3;
    Target target = 4;
    TargetOverride target_override = 5;
    TargetNode target_node = 6;
    TargetDefinition target_definition = 7;
    DefinitionLocation definition_location = 8;
    Override override = 9;
    Diagnostic diagnostic = 10;
  }

  // Index for columnar file decorations data.
  //
  // Columnar key: <empty>
  message Index {
    string text_encoding = 1;
  }

  // File contents (possibly partial) for FileDecorations.
  //
  // Columnar key: 00-start-end
  message Text {
    // Starting offset of this file contents piece.
    int32 start_offset = 1;
    // Ending offset of this file contents piece.
    int32 end_offset = 2;

    bytes text = 3;
  }

  // File decoration target
  //
  // Columnar key: 10-build_config-start-end-kind-target
  message Target {
    // Starting offset of this file decoration.
    int32 start_offset = 1;
    // Ending offset of this file decoration.
    int32 end_offset = 2;

    oneof kind {
      kythe.proto.schema.EdgeKind kythe_kind = 3;
      string generic_kind = 4;
    }

    kythe.proto.VName target = 5;

    string build_config = 6;
  }

  // Override per file decoration target node.
  //
  // Columnar key: 20-target-kind-override
  message TargetOverride {
    enum Kind {
      UNKNOWN = 0;
      OVERRIDES = 1;
      EXTENDS = 2;
    }

    // File decorations target node marked as overridden.
    kythe.proto.VName overridden = 1;
    Kind kind = 2;
    // Node that overrides the file decoration target node.
    kythe.proto.VName overriding = 3;
  }

  // File decorations target node.
  //
  // Columnar key: 30-target
  message TargetNode {
    kythe.proto.schema.Node node = 1;
  }

  // File decorations target node definition.
  //
  // Columnar key: 40-target
  message TargetDefinition {
    kythe.proto.VName target = 1;
    kythe.proto.VName definition = 2;
  }

  // Location for each node mentioned by a TargetDefinition
  //
  // Columnar key: 50-definition
  message DefinitionLocation {
    kythe.proto.serving.ExpandedAnchor location = 1;
  }

  // Override data for each overriding node mentioned in a TargetOverride.
  //
  // Columnar key: 60-override
  message Override {
    kythe.proto.VName override = 1;
    kythe.proto.common.MarkedSource marked_source = 2;
  }

  // Diagnostic per file span
  //
  // Columnar key: 70-start-end-hash
  // TODO(schroederc): add build_config to spanning Diagnostics and key
  message Diagnostic {
    kythe.proto.common.Diagnostic diagnostic = 1;
  }
}

// Columnar protocol buffer format for CrossReferences.
//
// Design: https://github.com/kythe/kythe/blob/master/kythe/docs/rfc/2909.md
//
// Columnar key prefix: "xr"-source
message CrossReferences {
  kythe.proto.VName source = 1;

  oneof entry {
    Index index = 2;
    Reference reference = 3;
    Relation relation = 4;
    Caller caller = 5;
    Callsite callsite = 6;
    RelatedNode related_node = 7;
    NodeDefinition node_definition = 8;
  }

  // Index for columnar cross-references data.
  //
  // Columnar key: <empty>
  message Index {
    kythe.proto.schema.Node node = 1;
    kythe.proto.common.MarkedSource marked_source = 2;
    repeated kythe.proto.VName merge_with = 3;
  }

  // Single reference to source.
  //
  // Columnar key: 00-kind-file-start-end
  message Reference {
    oneof kind {
      kythe.proto.schema.EdgeKind kythe_kind = 1;
      string generic_kind = 2;
    }
    kythe.proto.serving.ExpandedAnchor location = 3;

    // TODO(schroederc): add priority grouping
  }

  // Single edge relation to the source node.
  //
  // Columnar key: 10-kind-reverse-ordinal-target
  message Relation {
    // Target node of the relation
    kythe.proto.VName node = 1;
    // Relation to the node.
    oneof kind {
      kythe.proto.schema.EdgeKind kythe_kind = 2;
      string generic_kind = 3;
    }
    // Edge ordinal for this relation to the node.
    int32 ordinal = 4;
    // Whether the relation is a reverse edge.
    bool reverse = 5;

    // TODO(schroederc): add priority grouping
  }

  // A caller with callsites to the source node.
  //
  // Columnar key: 20-caller
  message Caller {
    kythe.proto.VName caller = 1;
    // Syntactic location of the caller.
    kythe.proto.serving.ExpandedAnchor location = 2;
    // MarkedSource of the caller.
    kythe.proto.common.MarkedSource marked_source = 3;
  }

  // A single callsite to the source node.
  //
  // Columnar key: 20-caller-kind-file-start-end
  message Callsite {
    kythe.proto.VName caller = 1;
    // Syntactic location of the callsite.
    kythe.proto.serving.ExpandedAnchor location = 2;
    Kind kind = 3;

    enum Kind {
      UNKNOWN = 0;
      DIRECT = 1;
      OVERRIDE = 2;
    }
  }

  // Node data for relations.
  //
  // Columnar key: 30-node
  message RelatedNode {
    kythe.proto.schema.Node node = 1;
  }

  // Definition location for each RelatedNode
  //
  // Columnar key: 40-node
  message NodeDefinition {
    kythe.proto.VName node = 1;
    kythe.proto.serving.ExpandedAnchor location = 2;
  }
}