go/src/infra/tricium/api/v1/data.proto

// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package tricium;

option go_package = "infra/tricium/api/v1;tricium";

// Tricium data types.
//
// Any data type provided or needed by a Tricium function.
message Data {
  // Available data types should be listed in this enum and have a
  // corresponding nested message with a mandatory platforms fields,
  // see GitFileDetails for field details.
  enum Type {
    NONE = 0;
    GIT_FILE_DETAILS = 1;
    FILES = 2;
    reserved 3;
    RESULTS = 4;
  }

  // File change status.
  //
  // This corresponds to the status field provided by Gerrit in FileInfo:
  // https://goo.gl/ABFHDg
  enum Status {
    MODIFIED = 0;
    ADDED = 1;
    DELETED = 2;
    RENAMED = 3;
    COPIED = 4;
    REWRITTEN = 5;
  }

  // Details for supported types, specifically whether a type is tied to
  // a platform.
  //
  // These type details are used to resolve data dependencies when
  // generating workflows.
  message TypeDetails {
    Type type = 1;
    bool is_platform_specific = 2;
  }


  // Details for retrieval of file content from a Git repository.
  //
  // In practice this was only used as an input to GitFileDetails,
  // and is now DEPRECATED.
  //
  // PATH: tricium/data/git_file_details.json
  message GitFileDetails {
    // The platforms this data is tied to encoded as a bitmap.
    //
    // The bit number for each platform should correspond to the enum
    // position number of the same platform in the Platform.Name enum.
    //
    // This includes the ANY platform, encoded as zero, which should
    // be used for any data that is not platform-specific.
    int64 platforms = 1;

    string repository = 2;
    string ref = 3;
    repeated File files = 4;

    string commit_message = 5;
  }


  // List of paths included in the analyzer input.
  //
  // PATH: tricium/data/files.json
  message Files {
    int64 platforms = 1;

    repeated File files = 3;

    string commit_message = 4;
  }

  message File {
    // Relative file path.
    //
    // The path is relative to the root of the repository being analyzed,
    // and the path separator character is "/".
    string path = 1;

    // Whether or not this file contains binary content (not text).
    bool is_binary = 2;

    // How the file was changed.
    Status status = 3;
  }

  // Results from running a Tricium analyzer.
  //
  // Results are returned to the Tricium service from Buildbucket
  // properties on executed Tricium recipes.
  //
  // PATH: tricium/data/results.json
  // BUILDBUCKET PROPERTIES: output.properties.comments
  //                         output.properties.num_comments
  message Results {
    int64 platforms = 1;

    // Zero or more results found as comments, either inline comments or change
    // comments (comments without line positions).
    repeated Comment comments = 2;

    // POSSIBLE EXTENSION: More kinds of results here, for instance, coverage.
  }


  // Results.Comment, results as comments.
  //
  // Similar content as that needed to provide robot comments in Gerrit,
  // https://gerrit-review.googlesource.com/Documentation/config-robot-comments.html
  message Comment {
    reserved 4;

    // Comment ID.
    //
    // This is an UUID generated by the Tricium service and used for tracking
    // of comment feedback. Analyzers should leave this field empty.
    string id = 1;

    // Category of the result, encoded as a path with the analyzer name as the
    // root, followed by an arbitrary number of subcategories, for example
    // "ClangTidy/llvm-header-guard".
    string category = 2;

    // Comment message. This should be a short message suitable as a code
    // review comment.
    string message = 3;

    // Path to the file this comment is for.
    //
    // If this path is the empty string, then the comment is on the commit
    // message text, rather than an actual file.
    string path = 5;

    // Position information. If start_line is omitted, then the comment
    // will be a file-level comment.
    int32 start_line = 6; // 1-based, inclusive.
    int32 end_line = 7;   // 1-based, inclusive.
    int32 start_char = 8; // 0-based, inclusive.
    int32 end_char = 9;   // 0-based, exclusive.

    // Suggested fixes for the identified issue.
    repeated Suggestion suggestions = 10;

    // When true, show on both changed and unchanged lines.
    // When false, only show on changed lines.
    bool show_on_unchanged_lines = 11;
  }

  // Suggested fix.
  //
  // A fix may include replacements in any file in the same repo as the file of
  // the corresponding comment.
  message Suggestion {
    // A brief description of the suggested fix.
    string description = 1;

    // Fix as a list of replacements.
    repeated Replacement replacements = 2;
  }

  // A suggested replacement.
  //
  // The replacement should be for one continuous section of a file.
  message Replacement {

    // Path to the file for this replacement.
    //
    // An empty string indicates the commit message.
    string path = 1;

    // A replacement string.
    string replacement = 2;

    // A continuous section of the file to replace.
    int32 start_line = 3; // 1-based, inclusive.
    int32 end_line = 4;   // 1-based, inclusive.
    int32 start_char = 5; // 0-based, inclusive.
    int32 end_char = 6;   // 0-based, exclusive.
  }
}