blob: bc6bb38a09299eb822342419620f2ba9ddefa53e [file] [log] [blame]
// 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;
}
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
// TODO: (yiwzhang) The bugs are currently for informal purpose only as well.
// No automation has been built upon that.
repeated MonorailBug monorail_bug = 4;
}
// The proto message that models a bug in the Monorail. The existence
// of 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 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;
}