warning.proto

// Copyright 2020 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

syntax = "proto3";

package recipe_engine;

// Container used to hold a collection warning definitions. Used for the
// purpose of parsing the warnings defined in the text proto format
message DefinitionCollection {
  // (optional) list of warning definitions.
  repeated Definition warning = 1;

  // (optional) contains the default values for fields in all MonorailBug
  // message proto instances enclosed in this DefinitionCollection.
  MonorailBugDefault monorail_bug_default = 2;

  // (optional) contains the default values for fields in all GoogleIssue
  // message proto instances enclosed in this DefinitionCollection.
  GoogleIssueDefault google_issue_default = 3;
}

message Definition {
  // (required) The unique identifier for a warning defined in this repo
  // Syntax: The name is required to be in all CAPS snake case and numbers are
  // allowed except for the first character (e.g. DEPRECATE_SOMETHING123).
  // This name should match regex: "^[A-Z][A-Z0-9]*(\_[A-Z0-9]+)*$"
  string name = 1;

  // (optional) Long description of the warning. Each string will be displayed
  // as a new line in the console output. Therefore, it is recommended to keep
  // the length of each string < 78 (80-2; 2 characters are for indentation).
  repeated string description = 2;

  // (optional) The deadline that the warning should be fixed before.
  // Syntax: The deadline must be in ISO 8601 date format (i.e. YYYY-MM-DD)
  // TODO: (yiwzhang) This date is currently for informal purpose only. No
  // action will be taken beyond that date. In the future, we can force
  // recipe test execution to error out once the deadline is passed
  string deadline = 3;

  // (optional) a list of monorail bugs associated with the current warning.
  repeated MonorailBug monorail_bug = 4;

  // (optional) a list of Google Issue tracker bugs associated with the current
  // warning.
  repeated GoogleIssue google_issue = 5;
}

// The proto message that models a bug in the Monorail issue tracker. The
// existence of the supplied bug won't be validated.
message MonorailBug {
  // (required if host is not provided in MonorailBugDefault) host name of
  // monorail. E.g. bugs.chromium.org
  string host = 1;
  // (required if project is not provided in MonorailBugDefault) name of the
  // project. E.g. chromium
  string project = 2;
  // (required) bug numeric id
  uint32 id = 3;
}

// The proto message that models a bug in the Google issue tracker. The
// existence of the supplied bug won't be validated.
message GoogleIssue {
  // (required if host is not provided in GoogleIssueDefault) host name of
  // google issue tracker. E.g. crbug.com
  string host = 1;
  // (required) bug numeric id
  uint32 id = 2;
}

message GoogleIssueDefault {
  // (optional) host name of google issue tracker, e.g. crbug.com
  string host = 1;
}

// The proto message that contains the default value for the MonorailBug proto
// message instance
message MonorailBugDefault {
  // (optional) host name of monorail. E.g. bugs.chromium.org
  string host = 1;
  // (optional) name of the project. E.g. chromium
  string project = 2;
}

// Container for a list of causes.
message Causes {
  repeated Cause causes = 1;
}

// Cause of why a warning is issued.
message Cause {
  oneof oneof_cause {
    CallSite call_site = 1;
    ImportSite import_site = 2;
  }
}

// Callsite models the cause of execution warning. Execution warning is issued
// when a developer declares a warning inside the method body of API class in a
// recipe module and the declaration is hit while running recipe tests. The
// frame that is calling the warned method will be considered as call site
// unless the function represented by that frame is escaped with such warning.
// Then we will walk up the call stack and attribute the next outer frame
// as call site and so on.
message CallSite {
  // (required) The frame of the call site
  Frame site = 1;
  // (optional) The call stack at the time warning is issued
  repeated Frame call_stack = 2;
}

// ImportSite models the cause of import warning. Import warning is issued when
// a recipe or recipe module depends on a module with warning declared. Such
// recipe or recipe module will be considered as import site.
message ImportSite {
  // Repo name that the recipe or recipe module is in
  string repo = 1;
  oneof location {
    // Name of recipe module
    string module = 2;
    // Name of recipe (e.g. `path/to/recipe` or 'module:run/recipe')
    string recipe = 3;
  }
}

// Simplified representation of a stack frame
message Frame {
  // Absolute file path that contains the code object frame is executing
  string file = 1;
  // Current line Number in the source code for the frame
  uint32 line = 2;
}