| /** |
| * @license |
| * Copyright 2020 Google LLC |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| import {CommentRange} from './core'; |
| import {ChangeInfo} from './rest-api'; |
| |
| export declare interface ChecksPluginApi { |
| /** |
| * Must only be called once. You cannot register twice. You cannot unregister. |
| */ |
| register(provider: ChecksProvider, config?: ChecksApiConfig): void; |
| |
| /** |
| * Forces Gerrit to call fetch() on the registered provider. Can be called |
| * when the provider has gotten an update and does not want wait for the next |
| * polling interval to pass. |
| */ |
| announceUpdate(): void; |
| |
| /** |
| * Updates an individual result. |
| * |
| * This can be used for lazy loading detailed information. For example, if you |
| * are using the `check-result-expanded` endpoint, then you can load more |
| * result details when the user expands a result row. |
| * |
| * The parameter `run` is only used to *find* the correct run for updating the |
| * result. It will only be used for comparing `change`, `patchset`, `attempt` |
| * and `checkName`. Its properties other than `results` will not be updated. |
| * |
| * For us being able to identify the result that you want to update you have |
| * to set the `externalId` property. An undefined `externalId` will result in |
| * an error. |
| */ |
| updateResult(run: CheckRun, result: CheckResult): void; |
| } |
| |
| export declare interface ChecksApiConfig { |
| /** |
| * How often should the provider be called for new CheckData while the user |
| * navigates change related pages and the browser tab remains visible? |
| * Set to 0 to disable polling. Default is 60 seconds. |
| */ |
| fetchPollingIntervalSeconds: number; |
| } |
| |
| export declare interface ChangeData { |
| changeNumber: number; |
| patchsetNumber: number; |
| patchsetSha: string; |
| repo: string; |
| commitMessage?: string; |
| changeInfo: ChangeInfo; |
| } |
| |
| export declare interface ChecksProvider { |
| /** |
| * Gerrit calls this method when ... |
| * - ... the change or diff page is loaded. |
| * - ... the user switches back to a Gerrit tab with a change or diff page. |
| * - ... while the tab is visible in a regular polling interval, see |
| * ChecksApiConfig. |
| */ |
| fetch(change: ChangeData): Promise<FetchResponse>; |
| } |
| |
| export declare interface FetchResponse { |
| responseCode: ResponseCode; |
| |
| /** Only relevant when the responseCode is ERROR. */ |
| errorMessage?: string; |
| |
| /** |
| * Only relevant when the responseCode is NOT_LOGGED_IN. |
| * Gerrit displays a "Login" button and calls this callback when the user |
| * clicks on the button. |
| */ |
| loginCallback?: () => void; |
| |
| /** |
| * Top-level actions that are not associated with a specific run or result. |
| * Will be shown as buttons in the header of the Checks tab. |
| */ |
| actions?: Action[]; |
| |
| /** |
| * Shown prominently in the change summary below the run chips. |
| */ |
| summaryMessage?: string; |
| |
| /** |
| * Top-level links that are not associated with a specific run or result. |
| * Will be shown as icons in the header of the Checks tab. |
| */ |
| links?: Link[]; |
| |
| runs?: CheckRun[]; |
| } |
| |
| export enum ResponseCode { |
| OK = 'OK', |
| ERROR = 'ERROR', |
| NOT_LOGGED_IN = 'NOT_LOGGED_IN', |
| } |
| |
| /** |
| * A CheckRun models an entity that has start/end timestamps and can be in |
| * either of the states RUNNABLE, RUNNING, COMPLETED. By itself it cannot model |
| * an error, neither can it be failed or successful by itself. A run can be |
| * associated with 0 to n results (see below). So until runs are completed the |
| * runs are more interesting for the user: What is going on at the moment? When |
| * runs are completed the users' interest shifts to results: What do I have to |
| * fix? The only actions that can be associated with runs are RUN and CANCEL. |
| */ |
| export declare interface CheckRun { |
| /** |
| * Gerrit requests check runs and results from the plugin by change number and |
| * patchset number. So these two properties can as well be left empty when |
| * returning results to the Gerrit UI and are thus optional. |
| */ |
| change?: number; |
| /** |
| * Typically only runs for the latest patchset are requested and presented. |
| * Older runs and their results are only available on request, e.g. by |
| * switching to another patchset in a dropdown |
| * |
| * TBD: Check data providers may decide that runs and results are applicable |
| * to a newer patchset, even if they were produced for an older, e.g. because |
| * only the commit message was changed. Maybe that warrants the addition of |
| * another optional field, e.g. `original_patchset`. |
| */ |
| patchset?: number; |
| /** |
| * The UI will focus on just the latest attempt per run. Former attempts are |
| * accessible, but initially collapsed/hidden. Lower number means older |
| * attempt. Every run has its own attempt numbering, so attempt 3 of run A is |
| * not directly related to attempt 3 of run B. |
| * |
| * The attempt number must be >=0. Only if you have just one RUNNABLE attempt, |
| * then you can leave it undefined. |
| * |
| * TBD: Optionally providing aggregate information about former attempts will |
| * probably be a useful feature, but we are deferring the exact data modeling |
| * of that to later. |
| */ |
| attempt?: number; |
| |
| /** |
| * An optional opaque identifier not used by Gerrit directly, but might be |
| * used by plugin extensions and callbacks. |
| */ |
| externalId?: string; |
| |
| // The following 3 properties are independent of this run *instance*. They |
| // just describe what the check is about and will be identical for other |
| // attempts or patchsets or changes. |
| |
| /** |
| * The unique name of the check. There can’t be two runs with the same |
| * change/patchset/attempt/checkName combination. |
| * Multiple attempts of the same run must have the same checkName. |
| * It should be expected that this string is cut off at ~30 chars in the UI. |
| * The full name will then be shown in a tooltip. |
| */ |
| checkName: string; |
| /** |
| * Optional description of the check. Only shown as a tooltip or in a |
| * hovercard. |
| */ |
| checkDescription?: string; |
| /** |
| * Optional http link to an external page with more detailed information about |
| * this run. Must begin with 'http'. |
| */ |
| checkLink?: string; |
| |
| /** |
| * RUNNABLE: Not run (yet). Mostly useful for runs that the user can trigger |
| * (see actions) and for indicating that a check was not run at a |
| * later attempt. Cannot contain results. |
| * RUNNING: The run is in progress. |
| * SCHEDULED: Refinement of RUNNING: The run was triggered, but is not yet |
| * running. It may have to wait for resources or for some other run |
| * to finish. The UI treats this mostly identical to RUNNING, but |
| * uses a differnt icon. |
| * COMPLETED: The attempt of the run has finished. Does not indicate at all |
| * whether the run was successful or not. Outcomes can and should |
| * be modeled using the CheckResult entity. |
| */ |
| status: RunStatus; |
| /** |
| * Optional short description of the run status. This is a plain string |
| * without styling or formatting options. It will only be shown as a tooltip |
| * or in a hovercard. |
| * |
| * Examples: |
| * "40 tests running, 30 completed: 0 failing so far", |
| * "Scheduled 5 minutes ago, not running yet". |
| */ |
| statusDescription?: string; |
| /** |
| * Optional http link to an external page with more detailed information about |
| * the run status. Must begin with 'http'. |
| */ |
| statusLink?: string; |
| |
| /** |
| * Optional reference to a Gerrit label (e.g. "Verified") that this result |
| * influences. Allows the user to understand and navigate the relationship |
| * between check runs/results and submit requirements, |
| * see also https://gerrit-review.googlesource.com/c/homepage/+/279176. |
| */ |
| labelName?: string; |
| |
| /** |
| * Optional callbacks to the plugin. Must be implemented individually by |
| * each plugin. The most important actions (which get special UI treatment) |
| * are: |
| * "Run" for RUNNABLE and COMPLETED runs. |
| * "Cancel" for RUNNING and SCHEDULED runs. |
| */ |
| actions?: Action[]; |
| |
| scheduledTimestamp?: Date; |
| startedTimestamp?: Date; |
| /** |
| * For RUNNING runs this is considered to be an estimate of when the run will |
| * be finished. |
| */ |
| finishedTimestamp?: Date; |
| |
| /** |
| * List of results produced by this run. |
| * RUNNABLE runs must not have results. |
| * RUNNING runs can contain (intermediate) results. |
| * Nesting the results in runs enforces that: |
| * - A run can have 0-n results. |
| * - A result is associated with exactly one run. |
| */ |
| results?: CheckResult[]; |
| } |
| |
| export declare interface Action { |
| name: string; |
| tooltip?: string; |
| /** |
| * Primary actions will get a more prominent treatment in the UI. For example |
| * primary actions might be rendered as buttons versus just menu entries in |
| * an overflow menu. |
| */ |
| primary?: boolean; |
| /** |
| * Summary actions will get an even more prominent treatment in the UI. They |
| * will show up in the checks summary right below the commit message. This |
| * only affects top-level actions (i.e. actions in FetchResponse). |
| */ |
| summary?: boolean; |
| /** |
| * Renders the action button in a disabled state. That can be useful for |
| * actions that are present most of the time, but sometimes don't apply. Then |
| * a grayed out button with a tooltip makes it easier for the user to |
| * understand why an expected action is not available. The tooltip should then |
| * contain a message about why the disabled state was set, not just about what |
| * the action would normally do. |
| */ |
| disabled?: boolean; |
| callback: ActionCallback; |
| } |
| |
| export type ActionCallback = ( |
| change: number, |
| patchset: number, |
| /** |
| * Identical to 'attempt' property of CheckRun. Not set for top-level |
| * actions. |
| */ |
| attempt: number | undefined, |
| /** |
| * Identical to 'externalId' property of CheckRun. Not set for top-level |
| * actions. |
| */ |
| externalId: string | undefined, |
| /** |
| * Identical to 'checkName' property of CheckRun. Not set for top-level |
| * actions. |
| */ |
| checkName: string | undefined, |
| /** Identical to 'name' property of Action entity. */ |
| actionName: string |
| /** |
| * If the callback does not return a promise, then the user will get no |
| * feedback from the Gerrit UI. This is adequate when the plugin opens a |
| * dialog for example. If a Promise<ActionResult> is returned, then Gerrit |
| * will show toasts for user feedback, see ActionResult below. |
| */ |
| ) => Promise<ActionResult> | undefined; |
| |
| /** |
| * Until the Promise<ActionResult> resolves (max. 5 seconds) Gerrit will show a |
| * toast with the message `Triggering action '${action.name}' ...`. |
| * |
| * When the promise resolves (within 5 seconds) then Gerrit will replace the |
| * toast with a new one with the message `${message}` and show it for 5 seconds. |
| * If `message` is empty or undefined, then the `Triggering ...` toast will just |
| * be hidden and no further toast will be shown. |
| */ |
| export declare interface ActionResult { |
| /** An empty errorMessage means success. */ |
| message?: string; |
| /** |
| * If true, then ChecksProvider.fetch() is called. Has the same affect as if |
| * the plugin would call announceUpdate(). So just for convenience. |
| */ |
| shouldReload?: boolean; |
| /** DEPRECATED: Use `message` instead. */ |
| errorMessage?: string; |
| } |
| |
| /** See CheckRun.status for documentation. */ |
| export enum RunStatus { |
| RUNNABLE = 'RUNNABLE', |
| RUNNING = 'RUNNING', |
| SCHEDULED = 'SCHEDULED', |
| COMPLETED = 'COMPLETED', |
| } |
| |
| export declare interface CheckResult { |
| /** |
| * An optional opaque identifier not used by Gerrit directly, but might be |
| * used by plugin extensions and callbacks. |
| */ |
| externalId?: string; |
| |
| /** |
| * SUCCESS: Indicates that some build, test or check is passing. A COMPLETED |
| * run without results will also be treated as "passing" and will get |
| * an artificial SUCCESS result. But you can also make this explicit, |
| * which also allows one run to have multiple "passing" results, |
| * maybe along with results of other categories. |
| * INFO: The user will typically not bother to look into this category, |
| * only for looking up something that they are searching for. Can be |
| * used for reporting secondary metrics and analysis, or a wider |
| * range of artifacts produced by the checks system. |
| * WARNING: A warning is something that should be read before submitting the |
| * change. The user should not ignore it, but it is also not blocking |
| * submit. It has a similar level of importance as an unresolved |
| * comment. |
| * ERROR: An error indicates that the change must not or cannot be submitted |
| * without fixing the problem. Errors will be visualized very |
| * prominently to the user. |
| * |
| * The ‘tags’ field below can be used for further categorization, e.g. for |
| * distinguishing FAILED vs TIMED_OUT. |
| */ |
| category: Category; |
| |
| /** |
| * Short description of the check result. |
| * |
| * It should be expected that this string might be cut off at ~80 chars in the |
| * UI. The full description will then be shown in a tooltip. |
| * This is a plain string without styling or formatting options. |
| * |
| * Examples: |
| * MessageConverterTest failed with: 'kermit' expected, but got 'ernie'. |
| * Binary size of javascript bundle has increased by 27%. |
| */ |
| summary: string; |
| |
| /** |
| * Exhaustive optional message describing the check result. |
| * Will be initially collapsed. Might potentially be very long, e.g. a log of |
| * MB size. The UI is not limiting this. Data providing plugins are |
| * responsible for not killing the browser. :-) |
| * |
| * For now this is just a plain unformatted string. The only formatting |
| * applied is the one that Gerrit also applies to human comments. TBD: Both |
| * human comments and check result messages should get richer formatting |
| * options. |
| */ |
| message?: string; |
| |
| /** |
| * Tags allow a plugins to further categorize a result, e.g. making a list |
| * of results filterable by the end-user. |
| * The name is free-form, but there is a predefined set of TagColors to |
| * choose from with a recommendation of color for common tags, see below. |
| * |
| * Examples: |
| * PASS, FAIL, SCHEDULED, OBSOLETE, SKIPPED, TIMED_OUT, INFRA_ERROR, FLAKY |
| * WIN, MAC, LINUX |
| * BUILD, TEST, LINT |
| * INTEGRATION, E2E, SCREENSHOT |
| */ |
| tags?: Tag[]; |
| |
| /** |
| * Links provide an opportunity for the end-user to easily access details and |
| * artifacts. Links are displayed by an icon+tooltip only. They don’t have a |
| * name, making them clearly distinguishable from tags and actions. |
| * |
| * There is a fixed set of LinkIcons to choose from, see below. |
| * |
| * Examples: |
| * Link to test log. |
| * Link to result artifacts such as images and screenshots. |
| * Link to downloadable artifacts such as ZIP or APK files. |
| */ |
| links?: Link[]; |
| |
| /** |
| * Link to lines of code. The referenced path must be part of this patchset. |
| * |
| * Only one code pointer is supported. If the array contains, more than one |
| * pointer, then all the other pointers will be ignored. Support for multiple |
| * code pointers will only added on demand. |
| */ |
| codePointers?: CodePointer[]; |
| |
| /** |
| * Callbacks to the plugin. Must be implemented individually by each |
| * plugin. Actions are rendered as buttons. If there are more than two actions |
| * per result, then further actions are put into an overflow menu. Sort order |
| * is defined by the data provider. |
| * |
| * Examples: |
| * Acknowledge/Dismiss, Delete, Report a bug, Report as not useful, |
| * Make blocking, Downgrade severity. |
| */ |
| actions?: Action[]; |
| } |
| |
| export enum Category { |
| SUCCESS = 'SUCCESS', |
| INFO = 'INFO', |
| WARNING = 'WARNING', |
| ERROR = 'ERROR', |
| } |
| |
| export declare interface Tag { |
| name: string; |
| tooltip?: string; |
| color?: TagColor; |
| } |
| |
| // TBD: Clarify standard colors for common tags. |
| export enum TagColor { |
| GRAY = 'gray', |
| YELLOW = 'yellow', |
| PINK = 'pink', |
| PURPLE = 'purple', |
| CYAN = 'cyan', |
| BROWN = 'brown', |
| } |
| |
| export declare interface Link { |
| /** Must begin with 'http'. */ |
| url: string; |
| tooltip?: string; |
| /** |
| * Primary links will get a more prominent treatment in the UI, e.g. being |
| * always visible in the results table or also showing up in the change page |
| * summary of checks. |
| */ |
| primary: boolean; |
| icon: LinkIcon; |
| } |
| |
| export declare interface CodePointer { |
| path: string; |
| range: CommentRange; |
| } |
| |
| export enum LinkIcon { |
| EXTERNAL = 'external', |
| IMAGE = 'image', |
| HISTORY = 'history', |
| DOWNLOAD = 'download', |
| DOWNLOAD_MOBILE = 'download_mobile', |
| HELP_PAGE = 'help_page', |
| REPORT_BUG = 'report_bug', |
| CODE = 'code', |
| FILE_PRESENT = 'file_present', |
| } |