kythe/proto/analysis.proto

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

option go_package = "analysis_go_proto";
option java_package = "com.google.devtools.kythe.proto";
option cc_enable_arenas = true;

import "google/protobuf/any.proto";
import "kythe/proto/storage.proto";

// An AnalysisRequest instructs an analyzer to perform an analysis on a single
// CompilationUnit.
message AnalysisRequest {
  // The compilation to analyze.
  CompilationUnit compilation = 1;

  // The address of a file data service to use.  If this is provided, it should
  // be used in preference to any other file data service the analyzer may know
  // about for this compilation.
  string file_data_service = 2;

  // The revision marker that should be attributed to this compilation.
  string revision = 3;

  // An identifier for the current analysis.
  string build_id = 4;
}

// AnalysisOutput contains an output artifact for the current analysis taking
// place.  A given analysis may not produce any outputs.  It is okay for an
// indexer to send an empty AnalysisOutput message if needed to keep the RPC
// channel alive; the driver must correctly handle this.
//
// The format of value is determined by the analyzer. Kythe language indexers
// emit wire-format kythe.proto.Entry messages.
message AnalysisOutput {
  bytes value = 1;

  // An analyzer may optionally report the final result of analysis by
  // populating this field in the last output it emits.
  //
  // Constraints: If final_result is set, value must be unset, and once a
  // final_result has been sent no further outputs may be sent. The driver must
  // enforce these constraints by aborting and discarding the request if the
  // analyzer sends additional data after the final_result. It is legal for the
  // analyzer to omit any final_result, in which case the driver will assume
  // that the analysis was completed successfully.
  AnalysisResult final_result = 10;

  // TODO(fromberger): Convert these fields to a single oneof, to enforce the
  // mutual exclusion explicitly. For now I'm leaving them separate to make it
  // easier to migrate existing uses.
}

// AnalysisResult documents the analyzer's opinion of an analysis request.
message AnalysisResult {
  enum Status {
    COMPLETE = 0;         // analysis completed successfully without error
    INCOMPLETE = 1;       // analysis ended after partial results
    INVALID_REQUEST = 2;  // the analysis request was invalid for this analyzer
  }

  Status status = 1;   // the status code describing the result
  string summary = 2;  // a human-readable error message for use in diagnostics
}

// Describes a single unit of compilation.
message CompilationUnit {
  // The base VName for the compilation and any VNames generated from its
  // analysis. The `v_name` field does not identify a compilation unit, but
  // provides the information the analyzer needs to correctly label the
  // entities described by its source. At minimum, this should include the
  // `corpus` and `language` the unit belongs to, and if appropriate the
  // `root`. The `v_name` of an object in the code is formed by merging its
  // specifics into this basis.
  //
  // This VName also serves as the default basis for any required inputs that
  // do not provide their own `v_name` field.  As such, the general logic for
  // constructing VNames for entities arising a given source path should be:
  // {
  //   corpus:   unit.required_input[path].v_name.corpus OR unit.v_name.corpus
  //   root:     unit.required_input[path].v_name.root OR unit.v_name.root
  //   path:     unit.required_input[path].v_name.path OR path
  // }
  // The above applies generally, but specific node kinds may have rules which
  // override this logic.
  VName v_name = 1;

  reserved 2;

  // All files that might be touched in the course of this compilation.
  // Consumers of the CompilationUnit may not assume anything about the order
  // of the elements of this field.
  repeated FileInput required_input = 3;

  // Set by the extractor to indicate that the original input had compile
  // errors. This is used to check validity of the sharded analysis.
  bool has_compile_errors = 4;

  // The arguments to pass to a compiler tool for this compilation unit,
  // including the compiler executable, flags, and input files.
  repeated string argument = 5;

  // Of those files in `required_input`, the ones that this CompilationUnit
  // is intended to analyze. This is necessary to support languages like Go,
  // where a single translation unit may contain many source files that must all
  // be processed at once (while excluding source files that belong to other
  // CUs/packages, if any).
  repeated string source_file = 6;

  // The output key of the CompilationUnit; for example, the object file that
  // it writes.  The output key for a compilation should match the path in the
  // FileInfo message of a dependent compilation that consumes its output.
  string output_key = 7;

  message FileInput {
    // If set, overrides the `v_name` in the `CompilationUnit` for deriving
    // VNames during analysis. Values for fields which are not explicitly set
    // should be taken from the CompilationUnit's VName or (for path) FileInfo.
    VName v_name = 1;

    // The file's metadata. It is invalid to provide a FileInput without both
    // the file's path and digest.
    FileInfo info = 2;

    reserved 3;

    // Per-language or per-tool details.
    repeated google.protobuf.Any details = 4;
  }

  // The absolute path of the current working directory where the build tool
  // was invoked.  During analysis, a file whose path has working_directory
  // plus a path separator as an exact prefix is considered accessible from
  // that same path without said prefix.  It is only necessary to set this
  // field if the build tool requires it.
  string working_directory = 8;

  // For languages that make use of resource contexts (like C++), the context
  // that should be initially entered.
  // TODO(zarko): What is a "resource context"? Needs a clear definition and/or
  // a link to one.
  string entry_context = 9;

  // An Env message represents the name and value of a single environment
  // variable in the build environment.
  message Env {
    string name = 1;
    string value = 2;
  }

  // A collection of environment variables that the build environment expects
  // to be set.  As a rule, we only record variables here that must be set to
  // specific values for the build to work.  Users of this field may not assume
  // anything about the order of values; in particular the pipeline is free to
  // sort by name in order to canonicalize the message.
  repeated Env environment = 10;

  // Per-language or per-tool details.
  repeated google.protobuf.Any details = 11;
}

// A FilesRequest specifies a collection of files to be fetched from a
// FileDataService.
message FilesRequest {
  repeated FileInfo files = 1;
}

// A FileInfo identifies a file used for analysis.
// At least one of the path and digest fields must be non-empty.
message FileInfo {
  // The path of the file relative to the working directory of the compilation
  // command, which is typically the root of the build.
  // For example:
  //  file/base/file.cc
  //  ../../base/atomic_ref_count.h
  string path = 1;

  // The lowercase ascii hex SHA-256 digest of the file contents.
  string digest = 2;
}

// A FileData carries the content of a single file, as returned from the Get
// method of a FileDataService.
message FileData {
  // The content of the file, if known.  If missing == true, this field must be
  // empty.
  bytes content = 1;

  // A (possibly normalized) copy of the non-empty fields of the FileInfo
  // message from the Get request.  If either field from the original request
  // was empty, the server may optionally fill in that field in the reply if it
  // is known.  For example, if the client requested a file by path only and
  // the server found it, the reply MAY fill in the digest.
  FileInfo info = 2;

  // If true, no data are available for the requested file, and the content
  // field must be empty.  If false, the content field contains the complete
  // file content (which may be empty).
  bool missing = 3;
}

// A CompilationBundle carries a CompilationUnit and its required FileData.
message CompilationBundle {
  // The CompilationUnit to be analyzed.
  CompilationUnit unit = 1;

  // File data for the CompilationUnit's required_input.
  repeated FileData files = 2;
}

// A compilation unit combined with index terms.
message IndexedCompilation {
  CompilationUnit unit = 1;
  Index index = 2;

  message Index {
    // Revision markers at which this compilation record is indexed.
    repeated string revisions = 1;
  }
}