| 1 | /** |
| 2 | * Checks: what CI, integrations and g1t's own workflows say about a |
| 3 | * commit. Statuses (a state per context) and check runs (a lifecycle, a |
| 4 | * conclusion, a Markdown report, annotations and buttons), grouped per |
| 5 | * reporter into check suites. A g1t Actions job is a check run too, and its |
| 6 | * workflow run the suite. Mirrors `crates/contracts/src/checks.rs`. |
| 7 | */ |
| 8 | |
| 9 | import type { RepoPath } from "./repos"; |
| 10 | import type { Result } from "./result"; |
| 11 | import type { User, Viewer } from "./identity"; |
| 12 | import type { CommitStatus } from "./work"; |
| 13 | |
| 14 | export type CheckRunStatus = "queued" | "in_progress" | "completed"; |
| 15 | export type CheckConclusion = "success" | "failure" | "neutral" | "cancelled" | "skipped" | "timed_out" | "action_required"; |
| 16 | export type AnnotationLevel = "notice" | "warning" | "failure"; |
| 17 | |
| 18 | /** Who reported a check run or suite. `actions` is g1t Actions. */ |
| 19 | export type CheckApp = { slug: string; name: string }; |
| 20 | |
| 21 | export type CheckAnnotation = { |
| 22 | path: string; |
| 23 | startLine: number; |
| 24 | endLine: number; |
| 25 | startColumn?: number; |
| 26 | endColumn?: number; |
| 27 | annotationLevel: AnnotationLevel; |
| 28 | message: string; |
| 29 | title?: string; |
| 30 | rawDetails?: string; |
| 31 | }; |
| 32 | |
| 33 | /** A button on a check run's page; pressing it sends `check_run.requested_action`. */ |
| 34 | export type CheckAction = { label: string; description: string; identifier: string }; |
| 35 | |
| 36 | export type CommitCheckRun = { |
| 37 | /** `cr_…`, or a g1t Actions job's `job_…`. */ |
| 38 | id: string; |
| 39 | name: string; |
| 40 | headSha: string; |
| 41 | status: CheckRunStatus; |
| 42 | conclusion: CheckConclusion | null; |
| 43 | startedAt: string | null; |
| 44 | completedAt: string | null; |
| 45 | /** The reporter's own page for it. */ |
| 46 | detailsUrl: string | null; |
| 47 | externalId: string | null; |
| 48 | /** Its page on the site, as a path. */ |
| 49 | htmlUrl: string; |
| 50 | output: { title: string | null; summary: string | null; text: string | null; annotationsCount: number }; |
| 51 | actions: CheckAction[]; |
| 52 | checkSuite: { id: string }; |
| 53 | app: CheckApp; |
| 54 | /** For a g1t Actions job: its workflow run. */ |
| 55 | workflow?: { runId: string; name: string; event: string }; |
| 56 | createdAt: string; |
| 57 | }; |
| 58 | |
| 59 | export type CommitCheckSuite = { |
| 60 | id: string; |
| 61 | headSha: string; |
| 62 | headBranch: string | null; |
| 63 | status: CheckRunStatus; |
| 64 | conclusion: CheckConclusion | null; |
| 65 | app: CheckApp; |
| 66 | name?: string; |
| 67 | latestCheckRunsCount: number; |
| 68 | createdAt: string; |
| 69 | updatedAt: string; |
| 70 | }; |
| 71 | |
| 72 | /** A check's state as one word. */ |
| 73 | export type CheckState = "success" | "failure" | "pending" | "neutral" | "skipped" | "cancelled"; |
| 74 | |
| 75 | /** One check as a commit's list shows it: a check run or a status, from any reporter (a deployment's included). */ |
| 76 | export type CheckItem = { |
| 77 | kind: "check_run" | "status"; |
| 78 | id: string | null; |
| 79 | name: string; |
| 80 | state: CheckState; |
| 81 | description: string | null; |
| 82 | /** The reporter's page for it. */ |
| 83 | detailsUrl: string | null; |
| 84 | /** Its page on g1t: a check run's, or a job's run. */ |
| 85 | url: string | null; |
| 86 | app: string | null; |
| 87 | startedAt: string | null; |
| 88 | completedAt: string | null; |
| 89 | }; |
| 90 | |
| 91 | /** Every check on one commit, and what they add up to. */ |
| 92 | export type CommitChecks = { |
| 93 | state: "success" | "failure" | "pending" | "none"; |
| 94 | total: number; |
| 95 | successful: number; |
| 96 | failed: number; |
| 97 | pending: number; |
| 98 | /** Neutral, skipped and cancelled. */ |
| 99 | skipped: number; |
| 100 | /** Failing first, then pending, then the rest. */ |
| 101 | checks: CheckItem[]; |
| 102 | }; |
| 103 | |
| 104 | /** Methods of the work service for checks. */ |
| 105 | export interface ChecksApi { |
| 106 | /** Every check on each of `shas` (at most 100), by SHA; commits nothing reported on are left out. */ |
| 107 | commitChecks(repo: RepoPath, viewer: Viewer, shas: string[]): Promise<Result<Record<string, CommitChecks>>>; |
| 108 | getCheckRun(repo: RepoPath, id: string, viewer: Viewer): Promise<Result<CommitCheckRun>>; |
| 109 | checkRunAnnotations(repo: RepoPath, id: string, viewer: Viewer): Promise<Result<CheckAnnotation[]>>; |
| 110 | /** Someone pressed one of a check run's buttons. */ |
| 111 | requestCheckAction(actor: User, repo: RepoPath, id: string, identifier: string): Promise<Result<boolean>>; |
| 112 | /** Asks the reporter to run it again; a g1t Actions job's run runs again. */ |
| 113 | rerequestCheckRun(actor: User, repo: RepoPath, id: string): Promise<Result<boolean>>; |
| 114 | } |
| 115 | |
| 116 | /** What `check_run.*` events carry. */ |
| 117 | export type CheckRunEventData = { repoId: string; checkRun: CommitCheckRun; requestedAction?: string }; |
| 118 | /** What `check_suite.*` events carry. */ |
| 119 | export type CheckSuiteEventData = { repoId: string; checkSuite: CommitCheckSuite }; |
| 120 | /** What `status.created` carries. */ |
| 121 | export type StatusEventData = { |
| 122 | repoId: string; |
| 123 | sha: string; |
| 124 | context: string; |
| 125 | state: CommitStatus["state"]; |
| 126 | description: string | null; |
| 127 | targetUrl: string | null; |
| 128 | }; |