go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/bisection/proto/v1/common.proto

// Copyright 2023 The LUCI Authors.
//
// 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 luci.bisection.v1;

import "google/protobuf/timestamp.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";

option go_package = "go.chromium.org/luci/bisection/proto/v1;bisectionpb";

// AnalysisStatus represents the result status of an analysis.
enum AnalysisStatus {
  ANALYSIS_STATUS_UNSPECIFIED = 0;
  // The analysis has been created, but not yet started.
  // We don't have this status in code. It's here for backward-compatability.
  CREATED = 1;
  // The analysis is running, but results have not been finalised.
  RUNNING = 2;
  // The analysis has finished and found (and verified) the culprit.
  FOUND = 3;
  // The analysis has finished but no culprit/suspect has been found.
  NOTFOUND = 4;
  // The analysis resulted in an error.
  ERROR = 5;
  // The analysis found some suspects, either from heuristic or nth-section.
  SUSPECTFOUND = 6;
  // The analysis is unsupported (unsupported project, test...).
  UNSUPPORTED = 7;
  // The analysis was disabled (e.g. from config).
  DISABLED = 8;
  // This status is to mark for the case when an analysis was created,
  // but was not sent to bisector, because we couldn't get sufficient data
  // to proceed.
  // One example is if we cannot get the commit ID for the regression range
  // because the commit was too old.
  INSUFFICENTDATA = 9;
}

enum RerunStatus {
  RERUN_STATUS_UNSPECIFIED = 0;
  // The rerun is in progress.
  // It may be scheduled or started, but not finished yet.
  RERUN_STATUS_IN_PROGRESS = 1;
  // For compile failure, it means the rerun succeeded.
  // For deterministic test failure, it means that the primary test failure
  // got expected result.
  RERUN_STATUS_PASSED = 2;
  // For compile failure, it means the compile was unsuccessful.
  // For deterministic test failure, it means that the primary test failure
  // got unexpected result.
  RERUN_STATUS_FAILED = 3;
  // The rerun ended with infra failure.
  // It means we will not know which direction to continue the bisection.
  // This case usually mean that the bisection will not be able to
  // find culprit.
  RERUN_STATUS_INFRA_FAILED = 4;
  // The rerun was canceled.
  RERUN_STATUS_CANCELED = 5;
  // Only used for test failure rerun.
  // The rerun ended, but the primary test failure was not run.
  // It usually means that we won't be able to continue the bisection.
  RERUN_STATUS_TEST_SKIPPED = 6;
}

// RerunResult contains the result of one rerun.
// It is for the bots to update result back to LUCI Bisection.
message RerunResult {
  // Status of the rerun.
  RerunStatus rerun_status = 1;
  // Error message, in case of FAILED or INFRA_FAILED status.
  string error_message = 2;
}

// SingleRerun contains information about a single rerun.
// The same bot may be reused for multiple rerun (to speed up compilation time).
message SingleRerun {
  // Timestamp for the created time of the rerun.
  google.protobuf.Timestamp start_time = 1;
  // Timestamp for the last updated time of the rerun.
  google.protobuf.Timestamp last_updated_time = 2;
  // Timestamp for the end time of the rerun.
  google.protobuf.Timestamp end_time = 3;
  // Buildbucket ID of the rerun build.
  int64 bbid = 4;
  // Task ID of the rerun.
  string task_id = 5;
  // ID of the bot.
  string bot_id = 6;
  // Result of the rerun.
  RerunResult rerun_result = 7;
  // Gitiles commit to do the rerun with.
  buildbucket.v2.GitilesCommit commit = 8;
  // Index of the commit to rerun within the blamelist, if this is an
  // nth-section rerun. We need to use a string instead of an int here because
  // 0 is a possible valid value but would get lost due to the "omitempty" flag
  // in the generated proto.
  string index = 9;
  // Type of rerun: either "Culprit Verification" or "NthSection".
  string type = 10;
}

message SuspectVerificationDetails {
  // The status of the suspect verification.
  string status = 1;
  // The verification rerun build for the suspect commit.
  SingleRerun suspect_rerun = 2;
  // The verification rerun build for the parent commit of the suspect.
  SingleRerun parent_rerun = 3;
}

// Variant represents a way of running a test case.
//
// The same test case can be executed in different ways, for example on
// different OS, GPUs, with different compile options or runtime flags.
message Variant {
  // The definition of the variant. Each key-value pair represents a
  // parameter describing how the test was run (e.g. OS, GPU, etc.).
  map<string, string> def = 1;
}

// Represents a reference in a source control system.
message SourceRef {
  // The source control system used.
  // Only gitiles is supported at this moment. If other systems need to be
  // supported in future (e.g. non-gitiles git, subversion, google storage
  // buckets), they can be added here
  oneof system {
    // A branch in gitiles repository.
    GitilesRef gitiles = 1;
  }
}

// Represents a branch in a gitiles repository.
message GitilesRef {
  // The gitiles host, e.g. "chromium.googlesource.com".
  string host = 1;

  // The project on the gitiles host, e.g. "chromium/src".
  string project = 2;

  // Commit ref, e.g. "refs/heads/main" from which the commit was fetched.
  // Not the branch name, use "refs/heads/branch"
  string ref = 3;
}

// Represents dimensions requested to buildbucket.
message Dimensions {
  // List of dimensions, ordered by key ascendingly.
  repeated Dimension dimensions = 1;
}

// Represent one dimension requested to buildbucket.
message Dimension {
  // Key, e.g. "os".
  string key = 1;
  // Value, e.g. "Ubuntu".
  string value = 2;
}

// Status of a test result.
// It is a mirror of luci.resultdb.v1.TestStatus, but the right to evolve
// it independently is reserved.
enum TestResultStatus {
  // Status was not specified.
  // Not to be used in actual test results; serves as a default value for an
  // unset field.
  TEST_RESULT_STATUS_UNSPECIFIED = 0;

  // The test case has passed.
  PASS = 1;

  // The test case has failed.
  // Suggests that the code under test is incorrect, but it is also possible
  // that the test is incorrect or it is a flake.
  FAIL = 2;

  // The test case has crashed during execution.
  // The outcome is inconclusive: the code under test might or might not be
  // correct, but the test+code is incorrect.
  CRASH = 3;

  // The test case has started, but was aborted before finishing.
  // A common reason: timeout.
  ABORT = 4;

  // The test case did not execute.
  // Examples:
  // - The execution of the collection of test cases, such as a test
  //   binary, was aborted prematurely and execution of some test cases was
  //   skipped.
  // - The test harness configuration specified that the test case MUST be
  //   skipped.
  SKIP = 5;
}

// AnalysisType specifies type of the analysis.
enum AnalysisType {
  ANALYSIS_TYPE_UNSPECIFIED = 0;
  // Compile analysis type.
  COMPILE_FAILURE_ANALYSIS = 1;
  // Test analysis type.
  TEST_FAILURE_ANALYSIS = 2;
}

enum SuspectVerificationStatus {
  SUSPECT_VERIFICATION_STATUS_UNSPECIFIED = 0;
  UNVERIFIED = 1;
  VERIFICATION_SCHEDULED = 2;
  UNDER_VERIFICATION = 3;
  CONFIRMED_CULPRIT = 4;
  VINDICATED = 5;
  VERIFICATION_ERROR = 6;
  VERIFICATION_CANCELED = 7;
}

// Status of a test verdict.
// It is a mirror of luci.resultdb.v1.TestVariantStatus.
enum TestVerdictStatus {
  // a test verdict must not have this status.
  // This is only used when filtering verdicts.
  TEST_VERDICT_STATUS_UNSPECIFIED = 0;
  // The test verdict has no exonerations, and all results are unexpected.
  UNEXPECTED = 10;
  // The test verdict has no exonerations, and all results are unexpectedly skipped.
  UNEXPECTEDLY_SKIPPED = 20;
  // The test verdict has no exonerations, and has both expected and unexpected
  // results.
  FLAKY = 30;
  // The test verdict has one or more test exonerations.
  EXONERATED = 40;
  // The test verdict has no exonerations, and all results are expected.
  EXPECTED = 50;
}