Sign in

flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp

g1t/crates/contracts/src/work.rs

1,644 lines54,157 bytesCodeBlame
1//! The work service: issues, pull requests, comments and sessions.
2//!
3//! Each `*Args` struct is the argument of the method of the same name,
4//! served at `POST /rpc/<method>`.
5//!
6//! Issues and pull requests share one sequence of numbers per repository,
7//! so `#12` names exactly one of them.
8
9use serde::{Deserialize, Serialize};
10
11use crate::repos::{CompareArgs, RepoPath};
12use crate::{User, Viewer};
13
14/// Labels every repository starts with. Any other label comes into being
15/// the first time it is put on an issue.
16pub const DEFAULT_LABELS: [&str; 5] = ["bug", "feature", "docs", "chore", "question"];
17
18/// `open` or `closed`: the filter on lists of issues and pull requests. An
19/// open pull request is a draft or one ready for review; a closed one was
20/// merged or closed without merging.
21#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
22#[serde(rename_all = "lowercase")]
23pub enum State {
24 Open,
25 Closed,
26}
27
28/// Why an issue was closed.
29#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
30#[serde(rename_all = "snake_case")]
31pub enum IssueReason {
32 /// The work was done. If a pull request did it, `resolved_by` names it.
33 Completed,
34 NotPlanned,
35}
36
37impl IssueReason {
38 pub fn as_str(self) -> &'static str {
39 match self {
40 IssueReason::Completed => "completed",
41 IssueReason::NotPlanned => "not_planned",
42 }
43 }
44}
45
46/// Something that should change in a repository: a bug, a feature, a
47/// question. Opened by a person, an agent or an integration. Pull requests
48/// are made against it; the one that is merged resolves it.
49#[derive(Clone, Debug, Serialize, Deserialize)]
50#[serde(rename_all = "camelCase")]
51pub struct Issue {
52 pub id: String,
53 pub repo_id: String,
54 /// Shown as `#12`.
55 pub number: u32,
56 pub title: String,
57 /// Markdown. Also what an agent is given to work from.
58 pub body: String,
59 pub labels: Vec<String>,
60 /// Commands that must pass for a pull request to be accepted.
61 pub checks: Vec<String>,
62 pub state: State,
63 /// Set when closed.
64 pub reason: Option<IssueReason>,
65 /// The number of the pull request whose merge closed this issue.
66 pub resolved_by: Option<u32>,
67 pub author: User,
68 /// RFC 3339.
69 pub created_at: String,
70 /// RFC 3339.
71 pub updated_at: String,
72 /// RFC 3339.
73 pub closed_at: Option<String>,
74 /// Pull requests made against this issue, in any state.
75 pub pull_count: u32,
76 pub comment_count: u32,
77 /// Usernames of the people it is assigned to.
78 #[serde(default)]
79 pub assignees: Vec<String>,
80 /// The numbers of the issues that have to be merged before this one is
81 /// worked on.
82 #[serde(default)]
83 pub blocked_by: Vec<u32>,
84 /// Whether a g1t agent takes it as soon as it can: at once, or when
85 /// what it is blocked by has merged.
86 #[serde(default)]
87 pub queued: bool,
88 /// The agent working on it now: the one behind its newest pull request
89 /// that is still in progress in a fork, such as `g1t-agent`.
90 #[serde(default)]
91 pub agent: Option<String>,
92}
93
94#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
95#[serde(rename_all = "lowercase")]
96pub enum PullStatus {
97 /// Still being worked on.
98 Draft,
99 /// Ready for review.
100 Open,
101 Merged,
102 /// Closed without merging.
103 Closed,
104}
105
106impl PullStatus {
107 pub fn as_str(self) -> &'static str {
108 match self {
109 PullStatus::Draft => "draft",
110 PullStatus::Open => "open",
111 PullStatus::Merged => "merged",
112 PullStatus::Closed => "closed",
113 }
114 }
115
116 /// Whether the pull request can still be changed or merged.
117 pub fn is_active(self) -> bool {
118 matches!(self, PullStatus::Draft | PullStatus::Open)
119 }
120}
121
122/// Where the agent runs: on g1t's sandboxes, or in someone's own session.
123#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
124#[serde(rename_all = "lowercase")]
125pub enum Runtime {
126 Hosted,
127 External,
128}
129
130/// A proposed change. It is made either in a fork created for it, which is
131/// how agents work, or on a branch pushed to the repository itself.
132#[derive(Clone, Debug, Serialize, Deserialize)]
133#[serde(rename_all = "camelCase")]
134pub struct Pull {
135 pub id: String,
136 pub repo_id: String,
137 /// Shown as `#12`.
138 pub number: u32,
139 /// The number of the issue this is for, if any.
140 pub issue: Option<u32>,
141 pub title: String,
142 /// Markdown: what changed and why. Set when marked ready.
143 pub body: Option<String>,
144 /// A label for the agent doing the work, e.g. `claude-code`.
145 pub agent: String,
146 pub runtime: Runtime,
147 pub status: PullStatus,
148 /// The fork holding the change, unless it is on a branch.
149 pub fork: Option<RepoPath>,
150 /// The fork's repository id.
151 pub fork_repo_id: Option<String>,
152 /// The branch of the repository holding the change, unless it is in a
153 /// fork.
154 pub branch: Option<String>,
155 pub head_commit: Option<String>,
156 /// For a merged pull request, what the branch pointed to before the
157 /// merge. Comparing against it shows what the pull request changed.
158 pub merge_base: Option<String>,
159 /// Username of whoever merged it.
160 pub merged_by: Option<String>,
161 /// RFC 3339.
162 pub merged_at: Option<String>,
163 /// Set on a pull request closed because another one for the same issue
164 /// was merged: that one's number.
165 pub superseded_by: Option<u32>,
166 /// Where the latest run of the issue's acceptance checks stands, if
167 /// there has been one against the current head.
168 pub check_status: Option<CheckStatus>,
169 /// The files it changes, as of its latest push.
170 #[serde(default)]
171 pub files: Vec<ChangedFile>,
172 /// Usernames of the people it is assigned to.
173 #[serde(default)]
174 pub assignees: Vec<String>,
175 /// Those whose review was asked for: usernames, and `g1t-agent` when a
176 /// g1t agent was asked.
177 #[serde(default)]
178 pub reviewers: Vec<String>,
179 pub author: User,
180 /// RFC 3339.
181 pub created_at: String,
182 /// RFC 3339.
183 pub updated_at: String,
184}
185
186/// One file a pull request changes, and by how much.
187#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
188pub struct ChangedFile {
189 pub path: String,
190 pub additions: u32,
191 pub deletions: u32,
192}
193
194/// Another pull request in progress that changes some of the same files.
195/// Two for the same issue are alternatives; two for different issues are
196/// heading for a conflict.
197#[derive(Clone, Debug, Serialize, Deserialize)]
198pub struct Overlap {
199 pub number: u32,
200 pub title: String,
201 /// The number of the issue the other pull request is for.
202 pub issue: Option<u32>,
203 /// The files both change.
204 pub paths: Vec<String>,
205}
206
207impl Pull {
208 /// What to ask the repos service to see what this pull request changes.
209 ///
210 /// A fork is compared as a whole. A branch is compared by name while
211 /// the pull request is open, and by the commit it was merged or closed
212 /// at afterwards, so later pushes to the branch do not change the record.
213 pub fn comparison(&self, viewer: &Viewer) -> CompareArgs {
214 let settled = matches!(self.status, PullStatus::Merged | PullStatus::Closed);
215 let (repo_id, head) = match &self.fork_repo_id {
216 Some(fork) => (fork.clone(), None),
217 None => (
218 self.repo_id.clone(),
219 self.head_commit
220 .clone()
221 .filter(|_| settled)
222 .or_else(|| self.branch.clone()),
223 ),
224 };
225 CompareArgs {
226 repo_id,
227 viewer: viewer.clone(),
228 base: self.merge_base.clone(),
229 head,
230 }
231 }
232}
233
234#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
235#[serde(rename_all = "lowercase")]
236pub enum CheckStatus {
237 /// Waiting for a sandbox.
238 Queued,
239 Running,
240 Passed,
241 Failed,
242 /// The checks could not be run at all.
243 Errored,
244}
245
246impl CheckStatus {
247 pub fn as_str(self) -> &'static str {
248 match self {
249 CheckStatus::Queued => "queued",
250 CheckStatus::Running => "running",
251 CheckStatus::Passed => "passed",
252 CheckStatus::Failed => "failed",
253 CheckStatus::Errored => "errored",
254 }
255 }
256}
257
258/// How one acceptance check went.
259#[derive(Clone, Debug, Serialize, Deserialize)]
260#[serde(rename_all = "camelCase")]
261pub struct CheckResult {
262 pub command: String,
263 pub passed: bool,
264 /// Absent when the command was stopped for taking too long.
265 #[serde(default)]
266 pub exit_code: Option<i32>,
267 /// What the command printed, standard output and error together. The
268 /// end of it, when there was a lot.
269 #[serde(default)]
270 pub output: String,
271 #[serde(default)]
272 pub duration_ms: u64,
273}
274
275/// One run of an issue's acceptance checks against a pull request's head,
276/// in a sandbox that holds nothing but that commit.
277#[derive(Clone, Debug, Serialize, Deserialize)]
278#[serde(rename_all = "camelCase")]
279pub struct CheckRun {
280 pub id: String,
281 /// The commit that was checked.
282 pub head_commit: String,
283 pub status: CheckStatus,
284 pub results: Vec<CheckResult>,
285 /// Why the checks could not be run, when `status` is `errored`.
286 pub error: Option<String>,
287 /// RFC 3339.
288 pub created_at: String,
289 /// RFC 3339.
290 pub finished_at: Option<String>,
291}
292
293/// A reviewer's decision on a pull request.
294#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
295#[serde(rename_all = "snake_case")]
296pub enum Verdict {
297 Approve,
298 RequestChanges,
299}
300
301impl Verdict {
302 pub fn as_str(self) -> &'static str {
303 match self {
304 Verdict::Approve => "approve",
305 Verdict::RequestChanges => "request_changes",
306 }
307 }
308}
309
310/// What an entry in a conversation is.
311#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
312#[serde(rename_all = "lowercase")]
313pub enum CommentKind {
314 /// Something a person or an agent wrote.
315 #[default]
316 Comment,
317 /// Something that happened: an assignment, a review asked for, a close.
318 Event,
319}
320
321/// A comment on an issue or a pull request. On a pull request it can sit
322/// on one line of the change, and it can carry a reviewer's verdict.
323#[derive(Clone, Debug, Serialize, Deserialize)]
324#[serde(rename_all = "camelCase")]
325pub struct Comment {
326 pub id: String,
327 /// Something a person wrote, or something that happened.
328 #[serde(default)]
329 pub kind: CommentKind,
330 pub author: User,
331 /// Markdown. For an event, what its author did, as the rest of a
332 /// sentence that starts with their name: "assigned ana".
333 pub body: String,
334 /// The file commented on, for a comment on a line.
335 pub path: Option<String>,
336 /// The line of that file, as numbered after the change.
337 pub line: Option<u32>,
338 pub verdict: Option<Verdict>,
339 /// RFC 3339.
340 pub created_at: String,
341}
342
343#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
344#[serde(rename_all = "snake_case")]
345pub enum SessionEntryKind {
346 Prompt,
347 Message,
348 ToolCall,
349 ToolResult,
350 Note,
351}
352
353/// One step of an agent's session: the "why" behind a pull request's commits.
354#[derive(Clone, Debug, Serialize, Deserialize)]
355pub struct SessionEntry {
356 pub seq: u32,
357 pub kind: SessionEntryKind,
358 pub text: String,
359 /// For tool calls and results.
360 pub tool: Option<String>,
361 /// The fork's head commit when this entry was recorded, if known.
362 pub commit: Option<String>,
363 /// RFC 3339.
364 pub at: String,
365}
366
367#[derive(Clone, Debug, Serialize, Deserialize)]
368pub struct NewSessionEntry {
369 pub kind: SessionEntryKind,
370 pub text: String,
371 #[serde(default)]
372 pub tool: Option<String>,
373 #[serde(default)]
374 pub commit: Option<String>,
375}
376
377#[derive(Clone, Debug, Serialize, Deserialize)]
378pub struct IssueDetail {
379 pub issue: Issue,
380 /// Every pull request made against it, oldest first.
381 pub pulls: Vec<Pull>,
382 pub comments: Vec<Comment>,
383}
384
385#[derive(Clone, Debug, Serialize, Deserialize)]
386pub struct PullDetail {
387 pub pull: Pull,
388 /// The issue it is for, if any.
389 pub issue: Option<Issue>,
390 pub comments: Vec<Comment>,
391 /// The latest run of the issue's acceptance checks.
392 pub checks: Option<CheckRun>,
393 /// Other pull requests in progress that change the same files.
394 #[serde(default)]
395 pub overlaps: Vec<Overlap>,
396 /// Whether the branch it would merge into has moved on without it, so
397 /// that it has to catch up before it can merge.
398 #[serde(default)]
399 pub behind: bool,
400 /// Whether a g1t agent is reviewing it right now.
401 #[serde(default)]
402 pub review_pending: bool,
403 /// Where it stands on its way to being merged, for a pull request g1t
404 /// is seeing through. Absent on anyone else's.
405 #[serde(default)]
406 pub lifecycle: Option<Lifecycle>,
407 /// A merge was asked for while it was behind: g1t is bringing it up to
408 /// date and will then land it.
409 #[serde(default)]
410 pub landing: bool,
411 /// Why g1t stopped working on it, if it did: a catch-up that could not
412 /// be completed, for example.
413 #[serde(default)]
414 pub stalled: Option<String>,
415 /// Messages people sent the agent while it worked, oldest first.
416 #[serde(default)]
417 pub messages: Vec<AgentMessage>,
418 /// What workflow runs said about its head commit, one per workflow.
419 #[serde(default)]
420 pub statuses: Vec<CommitStatus>,
421 /// Whether it merges cleanly into the branch it targets, worked out
422 /// ahead of time whenever either side moves.
423 #[serde(default)]
424 pub mergeable: Mergeable,
425 /// When `mergeable` is `conflicting`: the files that conflict.
426 #[serde(default)]
427 pub conflicts: Vec<String>,
428 /// Earlier runs of its acceptance checks, newest first, without their
429 /// output.
430 #[serde(default)]
431 pub earlier_checks: Vec<CheckRun>,
432}
433
434/// Whether a pull request's change merges cleanly into the branch it
435/// targets.
436#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
437#[serde(rename_all = "lowercase")]
438pub enum Mergeable {
439 /// It merges without conflicts.
440 Clean,
441 /// Some files conflict: see `PullDetail::conflicts`.
442 Conflicting,
443 /// Not known: never worked out, or it could not be.
444 #[default]
445 Unknown,
446 /// Being worked out now.
447 Checking,
448}
449
450impl Mergeable {
451 pub fn as_str(self) -> &'static str {
452 match self {
453 Mergeable::Clean => "clean",
454 Mergeable::Conflicting => "conflicting",
455 Mergeable::Unknown => "unknown",
456 Mergeable::Checking => "checking",
457 }
458 }
459
460 pub fn parse(value: Option<&str>) -> Mergeable {
461 match value {
462 Some("clean") => Mergeable::Clean,
463 Some("conflicting") => Mergeable::Conflicting,
464 Some("checking") => Mergeable::Checking,
465 _ => Mergeable::Unknown,
466 }
467 }
468}
469
470/// `start_mergecheck`: claims the probe of whether a pull request merges
471/// cleanly, which the work service asked for with a `pull.mergecheck`
472/// event. Called by the runner service, which starts the sandbox. Refused
473/// when it is no longer wanted, or when the repository already has as many
474/// probes running as it may. Returns `Outcome<MergecheckJob>`.
475#[derive(Debug, Serialize, Deserialize)]
476#[serde(rename_all = "camelCase")]
477pub struct StartMergecheckArgs {
478 pub pull_id: String,
479}
480
481/// What a sandbox needs to find out whether a pull request merges cleanly.
482#[derive(Debug, Serialize, Deserialize)]
483#[serde(rename_all = "camelCase")]
484pub struct MergecheckJob {
485 pub pull_id: String,
486 /// Lets the sandbox, and nothing else, report this probe.
487 pub token: String,
488 pub repo: RepoPath,
489 pub number: u32,
490 pub default_branch: String,
491 /// The default branch's commit to merge into.
492 pub base: String,
493 /// The repository holding the change: its fork, or the repository.
494 pub source: RepoPath,
495 /// The branch of `source` holding it.
496 pub branch: String,
497 /// The change's commit.
498 pub head: String,
499 /// Who opened the pull request, and so can read its source.
500 pub author: User,
501}
502
503/// `report_mergecheck`: what a sandbox found. Returns `Outcome<Mergeable>`.
504#[derive(Debug, Serialize, Deserialize)]
505#[serde(rename_all = "camelCase")]
506pub struct ReportMergecheckArgs {
507 pub pull_id: String,
508 pub token: String,
509 /// The files that conflict; empty when it merges cleanly.
510 #[serde(default)]
511 pub conflicts: Vec<String>,
512 /// Why it could not be found out.
513 #[serde(default)]
514 pub error: Option<String>,
515}
516
517/// What a workflow run (or another tool) says about a commit.
518#[derive(Clone, Debug, Serialize, Deserialize)]
519#[serde(rename_all = "camelCase")]
520pub struct CommitStatus {
521 /// What reported it, such as `CI / push`.
522 pub context: String,
523 /// `pending`, `success`, `failure` or `error`.
524 pub state: String,
525 pub description: Option<String>,
526 /// Where to see more, such as the run's page.
527 pub target_url: Option<String>,
528 pub updated_at: String,
529}
530
531/// `set_commit_status`: for services only. Returns `Outcome<bool>`.
532#[derive(Debug, Serialize, Deserialize)]
533#[serde(rename_all = "camelCase")]
534pub struct SetCommitStatusArgs {
535 pub repo_id: String,
536 pub sha: String,
537 pub context: String,
538 pub state: String,
539 #[serde(default)]
540 pub description: Option<String>,
541 #[serde(default)]
542 pub target_url: Option<String>,
543}
544
545/// A message a person sent an agent at work on a pull request. The agent
546/// receives it at its next step.
547#[derive(Clone, Debug, Serialize, Deserialize)]
548#[serde(rename_all = "camelCase")]
549pub struct AgentMessage {
550 pub id: String,
551 pub author: String,
552 pub body: String,
553 /// RFC 3339.
554 pub created_at: String,
555 /// RFC 3339. When the agent received it; null until then.
556 pub delivered_at: Option<String>,
557 /// `message` from a person, or from another pull request's agent a
558 /// `question`, a `handoff` of work, or the `answer` to one.
559 #[serde(default = "message_kind")]
560 pub kind: String,
561 /// The pull request whose agent sent it, when an agent did.
562 #[serde(default)]
563 pub from_number: Option<u32>,
564 /// The pull request it was sent to.
565 #[serde(default)]
566 pub to_number: u32,
567 /// For a question or handoff: the reply, once there is one.
568 #[serde(default)]
569 pub answer: Option<String>,
570 /// For a handoff: whether it was declined.
571 #[serde(default)]
572 pub declined: bool,
573 /// For the agent that sent it: what to expect, when the agent it asked
574 /// is not at work and will not answer soon.
575 #[serde(default, skip_serializing_if = "Option::is_none")]
576 pub hint: Option<String>,
577}
578
579fn message_kind() -> String {
580 "message".to_owned()
581}
582
583/// `message_agent`: sends the agent working on a pull request a message.
584/// The pull request's author and members of the workspace may. Returns
585/// `Outcome<AgentMessage>`.
586#[derive(Debug, Serialize, Deserialize)]
587pub struct MessageAgentArgs {
588 pub actor: User,
589 pub repo: RepoPath,
590 pub number: u32,
591 pub body: String,
592 /// For an agent: `question` or `handoff`; a person's is a `message`.
593 #[serde(default)]
594 pub kind: Option<String>,
595 /// For an agent: the pull request it is working on, which the reply
596 /// goes back to.
597 #[serde(default)]
598 pub from_number: Option<u32>,
599}
600
601/// `answer_message`: replies to a question or a handoff an agent received,
602/// accepting or declining a handoff. The reply reaches the asking agent at
603/// its next step. Returns `Outcome<AgentMessage>`, the message answered.
604#[derive(Debug, Serialize, Deserialize)]
605pub struct AnswerMessageArgs {
606 pub actor: User,
607 pub repo: RepoPath,
608 pub id: String,
609 pub body: String,
610 #[serde(default)]
611 pub decline: bool,
612}
613
614/// `take_messages`: the messages not yet delivered to the agent working on
615/// a pull request, marked delivered. Only g1t's agents may. Returns
616/// `Outcome<Vec<AgentMessage>>`.
617#[derive(Debug, Serialize, Deserialize)]
618pub struct TakeMessagesArgs {
619 pub actor: User,
620 pub repo: RepoPath,
621 pub number: u32,
622}
623
624/// A step on the way from an assigned issue to a pull request that is ready
625/// to merge. g1t takes each one without being asked.
626#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
627#[serde(rename_all = "snake_case")]
628pub enum Stage {
629 /// The agent is making the change.
630 Working,
631 /// The issue's acceptance checks are running against it.
632 Checking,
633 /// A g1t agent is reviewing it.
634 Reviewing,
635 /// The agent is addressing failed checks or a review.
636 Revising,
637 /// The agent is merging in the branch it would land on, which moved.
638 CatchingUp,
639 /// Woken to answer a question another agent asked it, or a handoff.
640 Answering,
641 /// In the repository's merge queue, being tested with what is ahead of
642 /// it before it lands.
643 Queued,
644 /// Checks passed, reviewed and approved, up to date. A person merges.
645 Ready,
646 /// g1t has stopped and a person has to decide what happens next.
647 NeedsYou,
648}
649
650/// Where a pull request made by a g1t agent stands. See [`Stage`].
651#[derive(Clone, Debug, Serialize, Deserialize)]
652pub struct Lifecycle {
653 pub stage: Stage,
654 /// One sentence saying what is happening, or why it stopped.
655 pub detail: String,
656 /// How many times the agent has been sent back to revise it.
657 pub revisions: u32,
658}
659
660/// `advance`: works out the next step for a pull request g1t is seeing
661/// through and, if there is one to take now, claims it, so that it is
662/// taken once however many times this is called. Called by the runner
663/// service, which carries the step out. Returns `Advance`.
664#[derive(Debug, Serialize, Deserialize)]
665#[serde(rename_all = "camelCase")]
666pub struct AdvanceArgs {
667 pub pull_id: String,
668}
669
670#[derive(Debug, Serialize, Deserialize)]
671#[serde(tag = "action", rename_all = "snake_case")]
672pub enum Advance {
673 /// Nothing to do now: a step is under way, or it is a person's turn.
674 None,
675 /// Have a g1t agent review it.
676 Review { job: LifecycleJob },
677 /// Send the agent back to address `job.feedback`.
678 Revise { job: LifecycleJob },
679 /// Merge in the branch it would land on.
680 CatchUp { job: LifecycleJob },
681}
682
683/// What the runner needs to carry out a step of a pull request's lifecycle.
684#[derive(Debug, Serialize, Deserialize)]
685#[serde(rename_all = "camelCase")]
686pub struct LifecycleJob {
687 pub pull_id: String,
688 pub repo: RepoPath,
689 pub number: u32,
690 /// Who the pull request belongs to. Sandboxes act as them.
691 pub author: User,
692 /// The repository holding the change: its fork, or the repository
693 /// itself for one made on a branch.
694 pub source: RepoPath,
695 /// The branch of the source holding the change; its default branch
696 /// when absent.
697 #[serde(default)]
698 pub branch: Option<String>,
699 pub default_branch: String,
700 pub title: String,
701 pub description: String,
702 pub issue: Option<Issue>,
703 /// For a revision: the failed checks or the review to address.
704 pub feedback: String,
705 /// For a revision: which one this is, from 1.
706 pub round: u32,
707}
708
709/// How a repository wants its pull requests handled. A repository that has
710/// changed nothing has the defaults.
711#[derive(Clone, Debug, Serialize, Deserialize)]
712#[serde(rename_all = "camelCase", default)]
713pub struct RepoSettings {
714 /// Land a g1t agent's pull request without a person once it is ready:
715 /// checks passed and approved as the settings below require.
716 pub auto_merge: bool,
717 /// Refuse to merge a pull request that does not contain the default
718 /// branch's latest commits, so that what merges is what was checked.
719 /// When off, merging one that is behind brings it up to date first.
720 pub require_up_to_date: bool,
721 /// How many approving reviews a pull request needs before it may
722 /// merge. A reviewer who has since asked for changes blocks it.
723 pub required_approvals: u32,
724 /// Whether a g1t agent's approval counts towards `required_approvals`.
725 pub count_agent_approvals: bool,
726 /// Whether a member may merge although the acceptance checks did not
727 /// pass.
728 pub allow_ignoring_checks: bool,
729 /// Whether a g1t agent's pull request is reviewed by a second agent
730 /// without being asked.
731 pub agent_review: bool,
732 /// How many times a g1t agent is sent back to its pull request before
733 /// a person is asked instead.
734 pub max_revisions: u32,
735 /// Merge through a queue: pull requests are tested together with those
736 /// ahead of them, and only a combination that passed reaches the default
737 /// branch.
738 pub merge_queue: bool,
739 /// Username of the member who last changed the settings, if anyone has.
740 pub updated_by: Option<String>,
741 /// RFC 3339.
742 pub updated_at: Option<String>,
743}
744
745impl Default for RepoSettings {
746 fn default() -> Self {
747 RepoSettings {
748 auto_merge: false,
749 require_up_to_date: false,
750 required_approvals: 0,
751 count_agent_approvals: true,
752 allow_ignoring_checks: true,
753 agent_review: true,
754 max_revisions: 2,
755 merge_queue: false,
756 updated_by: None,
757 updated_at: None,
758 }
759 }
760}
761
762/// `update_settings`: replaces a repository's settings. Members of its
763/// workspace only. Returns `Outcome<RepoSettings>`. `get_settings` takes
764/// `ViewArgs` and returns the same.
765#[derive(Debug, Serialize, Deserialize)]
766pub struct UpdateSettingsArgs {
767 pub actor: User,
768 pub repo: RepoPath,
769 /// Who changed them and when are filled in by the service.
770 pub settings: RepoSettings,
771}
772
773/// `catch_up_job`: what the runner needs to bring a pull request up to date
774/// because a merge of it was asked for. Null if none was. Returns
775/// `Option<LifecycleJob>`.
776#[derive(Debug, Serialize, Deserialize)]
777#[serde(rename_all = "camelCase")]
778pub struct CatchUpJobArgs {
779 pub pull_id: String,
780}
781
782/// `wake_for_messages`: the agent on a pull request was asked a question
783/// or handed work while it was not at work. Claims a short step for it to
784/// answer, and hands over what it was sent, marked read. Null when there
785/// is nothing waiting, or the pull request cannot take a step now.
786/// Returns `Option<Wake>`.
787#[derive(Debug, Serialize, Deserialize)]
788#[serde(rename_all = "camelCase")]
789pub struct WakeForMessagesArgs {
790 pub pull_id: String,
791}
792
793/// What an agent woken to answer needs: its pull request, and what it was
794/// sent, oldest first.
795#[derive(Debug, Serialize, Deserialize)]
796#[serde(rename_all = "camelCase")]
797pub struct Wake {
798 pub job: LifecycleJob,
799 pub messages: Vec<AgentMessage>,
800}
801
802/// `stall`: records that a step could not be carried out, so that g1t
803/// stops and a person is asked. Returns `bool`.
804#[derive(Debug, Serialize, Deserialize)]
805#[serde(rename_all = "camelCase")]
806pub struct StallArgs {
807 pub pull_id: String,
808 pub reason: String,
809}
810
811/// `managed_pulls`: ids of the open pull requests g1t is seeing through,
812/// in one repository or in all of them. Returns `Vec<String>`.
813#[derive(Debug, Default, Serialize, Deserialize)]
814#[serde(rename_all = "camelCase")]
815pub struct ManagedPullsArgs {
816 #[serde(default)]
817 pub repo_id: Option<String>,
818}
819
820/// `open_issue`. Returns `Outcome<Issue>`.
821#[derive(Debug, Serialize, Deserialize)]
822pub struct OpenIssueArgs {
823 pub actor: User,
824 pub repo: RepoPath,
825 pub title: String,
826 #[serde(default)]
827 pub body: String,
828 #[serde(default)]
829 pub labels: Vec<String>,
830 #[serde(default)]
831 pub checks: Vec<String>,
832}
833
834/// `list_issues`, newest first. Returns `Outcome<Vec<Issue>>`.
835#[derive(Debug, Serialize, Deserialize)]
836pub struct ListIssuesArgs {
837 pub repo: RepoPath,
838 pub viewer: Viewer,
839 #[serde(default)]
840 pub state: Option<State>,
841 /// Only issues carrying this label.
842 #[serde(default)]
843 pub label: Option<String>,
844}
845
846/// `list_pulls`, newest first. Returns `Outcome<Vec<Pull>>`.
847#[derive(Debug, Serialize, Deserialize)]
848pub struct ListPullsArgs {
849 pub repo: RepoPath,
850 pub viewer: Viewer,
851 #[serde(default)]
852 pub state: Option<State>,
853}
854
855/// `get_issue` (`Outcome<IssueDetail>`), `get_pull` (`Outcome<PullDetail>`),
856/// `read_session` (`Outcome<Vec<SessionEntry>>`), `list_labels`
857/// (`Outcome<Vec<String>>`) and `counts` (`Outcome<Counts>`). The last two
858/// ignore `number`.
859#[derive(Debug, Serialize, Deserialize)]
860#[serde(rename_all = "camelCase")]
861pub struct ViewArgs {
862 pub repo: RepoPath,
863 #[serde(default)]
864 pub number: u32,
865 pub viewer: Viewer,
866 /// For `read_session`: only entries after this sequence number.
867 #[serde(default)]
868 pub after_seq: u32,
869}
870
871/// How many issues and pull requests are open on a repository.
872#[derive(Debug, Serialize, Deserialize)]
873pub struct Counts {
874 pub issues: u32,
875 pub pulls: u32,
876}
877
878/// `update_issue`: changes whichever fields are given. The author or a
879/// member of the workspace may. Returns `Outcome<Issue>`.
880#[derive(Debug, Serialize, Deserialize)]
881pub struct UpdateIssueArgs {
882 pub actor: User,
883 pub repo: RepoPath,
884 pub number: u32,
885 #[serde(default)]
886 pub title: Option<String>,
887 #[serde(default)]
888 pub body: Option<String>,
889 #[serde(default)]
890 pub labels: Option<Vec<String>>,
891 /// Usernames of the people it is assigned to; replaces the whole set.
892 /// Assigning it to the g1t agent is the runner's `run`, not this.
893 #[serde(default)]
894 pub assignees: Option<Vec<String>>,
895}
896
897/// `close_issue` and `reopen_issue`. Each returns `Outcome<Issue>`.
898#[derive(Debug, Serialize, Deserialize)]
899pub struct IssueActionArgs {
900 pub actor: User,
901 pub repo: RepoPath,
902 pub number: u32,
903 /// For `close_issue`; `completed` if left out.
904 #[serde(default)]
905 pub reason: Option<IssueReason>,
906}
907
908/// `add_comment`, on an issue or a pull request. On a pull request it may
909/// name a line of the change, and may carry a verdict; nobody can give a
910/// verdict on their own pull request. Returns `Outcome<Comment>`.
911#[derive(Debug, Serialize, Deserialize)]
912pub struct AddCommentArgs {
913 pub actor: User,
914 pub repo: RepoPath,
915 pub number: u32,
916 /// May be empty when approving.
917 #[serde(default)]
918 pub body: String,
919 #[serde(default)]
920 pub path: Option<String>,
921 #[serde(default)]
922 pub line: Option<u32>,
923 #[serde(default)]
924 pub verdict: Option<Verdict>,
925}
926
927/// `open_pull`. Without `branch`, forks the repo and returns a draft pull
928/// request to push to. With it, opens a pull request, ready for review,
929/// for a branch already pushed to the repo. Returns `Outcome<Pull>`.
930#[derive(Debug, Serialize, Deserialize)]
931pub struct OpenPullArgs {
932 pub actor: User,
933 pub repo: RepoPath,
934 /// The issue this is for.
935 #[serde(default)]
936 pub issue: Option<u32>,
937 /// Defaults to the issue's title; required without an issue.
938 #[serde(default)]
939 pub title: String,
940 /// What changed and why. Usually set later, when a draft is marked ready.
941 #[serde(default)]
942 pub body: String,
943 /// A branch of the repository that already holds the change.
944 #[serde(default)]
945 pub branch: Option<String>,
946 #[serde(default)]
947 pub agent: String,
948 pub runtime: Runtime,
949}
950
951/// `ready_pull`, `close_pull` and `merge_pull`. Each returns `Outcome<Pull>`.
952///
953/// Also `catch_up_pull`: brings the pull request up to date with the
954/// default branch without a sandbox where that is safe, as the repos
955/// service's `update_pull_branch` does, after checking that `actor` may
956/// update it: whoever opened it for a fork, any member for a branch.
957/// Returns `Outcome<repos::PullBranchUpdate>`; on `needs_agent` nothing was
958/// pushed and the runner's `update` is the way on.
959#[derive(Debug, Serialize, Deserialize)]
960#[serde(rename_all = "camelCase")]
961pub struct PullActionArgs {
962 pub actor: User,
963 pub repo: RepoPath,
964 pub number: u32,
965 /// For `ready_pull`: what changed and why.
966 #[serde(default)]
967 pub summary: String,
968 /// For `merge_pull`: leave the issue open and the other pull requests
969 /// for it untouched, because this one is only part of the work.
970 #[serde(default)]
971 pub keep_issue_open: bool,
972 /// For `merge_pull`: merge although the acceptance checks have not
973 /// passed.
974 #[serde(default)]
975 pub ignore_checks: bool,
976}
977
978/// Where a plan stands.
979#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
980#[serde(rename_all = "lowercase")]
981pub enum PlanStatus {
982 /// An agent is reading the repository and writing it.
983 Planning,
984 /// Written, and waiting for a person to read and apply it.
985 Ready,
986 /// It could not be written.
987 Failed,
988 /// Its issues have been opened.
989 Applied,
990}
991
992/// One issue a plan proposes.
993#[derive(Clone, Debug, Default, Serialize, Deserialize)]
994#[serde(rename_all = "camelCase", default)]
995pub struct PlannedIssue {
996 pub title: String,
997 /// Markdown: what to change, where, and why.
998 pub body: String,
999 pub labels: Vec<String>,
1000 /// Commands that must pass once the change is made.
1001 pub checks: Vec<String>,
1002 /// The files it will most likely change.
1003 pub files: Vec<String>,
1004 /// The positions, counting from 1, of earlier issues in the plan that
1005 /// have to be merged first. An agent writes this as `depends_on`.
1006 #[serde(alias = "depends_on")]
1007 pub depends_on: Vec<u32>,
1008 /// Its number, once the plan has been applied and it was kept.
1009 pub number: Option<u32>,
1010}
1011
1012/// An outcome someone wrote, and the issues an agent proposes to get there.
1013#[derive(Clone, Debug, Serialize, Deserialize)]
1014#[serde(rename_all = "camelCase")]
1015pub struct Plan {
1016 pub id: String,
1017 pub repo_id: String,
1018 /// The outcome wanted, as written.
1019 pub brief: String,
1020 pub status: PlanStatus,
1021 /// The agent's account of how it split the work.
1022 pub summary: String,
1023 pub issues: Vec<PlannedIssue>,
1024 /// Why it could not be written, when `status` is `failed`.
1025 pub error: Option<String>,
1026 pub author: User,
1027 /// RFC 3339.
1028 pub created_at: String,
1029 /// RFC 3339.
1030 pub finished_at: Option<String>,
1031 /// Once applied: where each issue it opened stands now, in plan order.
1032 /// Filled in by `get_plan` only.
1033 #[serde(default)]
1034 pub progress: Vec<IssueProgress>,
1035 /// Questions and handoffs between the agents on its pull requests,
1036 /// newest first. Filled in by `get_plan` only.
1037 #[serde(default)]
1038 pub exchanges: Vec<AgentMessage>,
1039}
1040
1041/// Where one issue of an applied plan stands.
1042#[derive(Clone, Debug, Serialize, Deserialize)]
1043#[serde(rename_all = "camelCase")]
1044pub struct IssueProgress {
1045 pub number: u32,
1046 pub title: String,
1047 /// `blocked` (waiting on issues it depends on), `waiting` (for an
1048 /// agent), `open` (nobody on it), one of the lifecycle stages
1049 /// (`working`, `checking`, `reviewing`, `revising`, `catching_up`,
1050 /// `answering`, `queued`, `ready`, `needs_you`), `landed` or `closed`.
1051 pub state: String,
1052 /// One sentence about where it stands.
1053 pub detail: String,
1054 /// The issues it is waiting on that are still open.
1055 pub blocked_by: Vec<u32>,
1056 /// The pull request carrying it, the newest if several.
1057 pub pull: Option<u32>,
1058 /// Who or what is working on it, e.g. `g1t-agent`.
1059 pub agent: Option<String>,
1060}
1061
1062/// `start_plan`: records an outcome to plan for. Members of the
1063/// repository's workspace only. Called by the runner service, which starts
1064/// the sandbox. Returns `Outcome<PlanJob>`.
1065#[derive(Debug, Serialize, Deserialize)]
1066pub struct StartPlanArgs {
1067 pub actor: User,
1068 pub repo: RepoPath,
1069 pub brief: String,
1070}
1071
1072/// What a sandbox needs to write a plan.
1073#[derive(Debug, Serialize, Deserialize)]
1074#[serde(rename_all = "camelCase")]
1075pub struct PlanJob {
1076 pub plan_id: String,
1077 /// Lets the sandbox, and nothing else, report this plan.
1078 pub token: String,
1079 pub brief: String,
1080 pub repo: RepoPath,
1081}
1082
1083/// `report_plan`: the plan a sandbox's agent wrote, or why it could not
1084/// write one. Returns `Outcome<bool>`.
1085#[derive(Debug, Serialize, Deserialize)]
1086#[serde(rename_all = "camelCase")]
1087pub struct ReportPlanArgs {
1088 pub plan_id: String,
1089 pub token: String,
1090 #[serde(default)]
1091 pub summary: String,
1092 #[serde(default)]
1093 pub issues: Vec<PlannedIssue>,
1094 #[serde(default)]
1095 pub error: Option<String>,
1096}
1097
1098/// `get_plan`. Members only. Returns `Outcome<Plan>`. `list_plans` takes
1099/// `ViewArgs` and returns `Outcome<Vec<Plan>>`, newest first.
1100#[derive(Debug, Serialize, Deserialize)]
1101pub struct PlanArgs {
1102 pub repo: RepoPath,
1103 pub viewer: Viewer,
1104 pub id: String,
1105}
1106
1107/// `apply_plan`: opens a plan's issues, each blocked by the ones it depends
1108/// on. Members only, and once. Returns `Outcome<Plan>`, its issues now
1109/// carrying their numbers.
1110#[derive(Debug, Serialize, Deserialize)]
1111pub struct ApplyPlanArgs {
1112 pub actor: User,
1113 pub repo: RepoPath,
1114 pub id: String,
1115 /// Queue every issue for a g1t agent.
1116 #[serde(default)]
1117 pub assign: bool,
1118 /// The positions, counting from 1, of the issues to open. All of them
1119 /// when absent.
1120 #[serde(default)]
1121 pub keep: Option<Vec<u32>>,
1122}
1123
1124/// `queue_issue`: asks for a g1t agent to take an issue as soon as it can,
1125/// or withdraws that. The author or a member may. Returns `Outcome<bool>`.
1126#[derive(Debug, Serialize, Deserialize)]
1127pub struct QueueIssueArgs {
1128 pub actor: User,
1129 pub repo: RepoPath,
1130 pub number: u32,
1131 pub queued: bool,
1132}
1133
1134/// `ready_issues`: issues waiting for a g1t agent that can be given one
1135/// now, in one repository or in all. Called by the runner service. Returns
1136/// `Vec<ReadyIssue>`.
1137#[derive(Debug, Default, Serialize, Deserialize)]
1138#[serde(rename_all = "camelCase")]
1139pub struct ReadyIssuesArgs {
1140 #[serde(default)]
1141 pub repo_id: Option<String>,
1142}
1143
1144#[derive(Debug, Serialize, Deserialize)]
1145pub struct ReadyIssue {
1146 pub repo: RepoPath,
1147 pub number: u32,
1148 /// Who queued it, on whose say-so the agent works.
1149 pub actor: User,
1150}
1151
1152/// `update_pull`: changes who a pull request is assigned to and whose
1153/// review is asked for. Each list given replaces the whole set. Whoever
1154/// opened it, or a member of the workspace, may. Returns `Outcome<Pull>`.
1155#[derive(Debug, Serialize, Deserialize)]
1156pub struct UpdatePullArgs {
1157 pub actor: User,
1158 pub repo: RepoPath,
1159 pub number: u32,
1160 #[serde(default)]
1161 pub assignees: Option<Vec<String>>,
1162 /// May include `g1t-agent`. Asking for its review does not by itself
1163 /// start one; the runner's `review` does.
1164 #[serde(default)]
1165 pub reviewers: Option<Vec<String>>,
1166}
1167
1168/// `start_checks`: begins a run of the acceptance checks for a pull request
1169/// that is ready for review. Called by the runner service, which starts the
1170/// sandbox. Returns `Outcome<CheckJob>`.
1171#[derive(Debug, Serialize, Deserialize)]
1172#[serde(rename_all = "camelCase")]
1173pub struct StartChecksArgs {
1174 pub pull_id: String,
1175}
1176
1177/// What a sandbox needs to carry out a check run.
1178#[derive(Debug, Serialize, Deserialize)]
1179#[serde(rename_all = "camelCase")]
1180pub struct CheckJob {
1181 pub run_id: String,
1182 /// Lets the sandbox, and nothing else, report this run's results.
1183 pub token: String,
1184 pub commands: Vec<String>,
1185 /// The repository holding the commit: the fork, or the repository itself.
1186 pub source: RepoPath,
1187 pub commit: String,
1188 /// Who opened the pull request, and so can read its source.
1189 pub author: User,
1190 /// Username of whoever wrote the checks: the issue's author.
1191 pub requested_by: String,
1192 pub repo: RepoPath,
1193 pub number: u32,
1194}
1195
1196/// `report_checks`: what a sandbox says about its run. With no results and
1197/// no error it has started. `skip` forgets the run, for one that will not
1198/// be carried out. Returns `Outcome<CheckRun>`.
1199#[derive(Debug, Serialize, Deserialize)]
1200#[serde(rename_all = "camelCase")]
1201pub struct ReportChecksArgs {
1202 pub run_id: String,
1203 pub token: String,
1204 #[serde(default)]
1205 pub results: Vec<CheckResult>,
1206 #[serde(default)]
1207 pub error: Option<String>,
1208 #[serde(default)]
1209 pub skip: bool,
1210}
1211
1212/// A pull request in progress, with where it lives.
1213#[derive(Debug, Serialize, Deserialize)]
1214pub struct ActivePull {
1215 pub pull: Pull,
1216 pub issue: Option<Issue>,
1217 /// Where it stands, for one g1t is seeing through.
1218 #[serde(default)]
1219 pub lifecycle: Option<Lifecycle>,
1220}
1221
1222/// `list_active_pulls`: drafts and open pull requests the viewer started,
1223/// most recently active first. Returns `Vec<ActivePull>`. Also
1224/// `list_assigned_issues`: open issues assigned to the viewer, most
1225/// recently changed first. Returns `Vec<Issue>`.
1226#[derive(Debug, Serialize, Deserialize)]
1227pub struct ViewerArgs {
1228 pub viewer: Viewer,
1229}
1230
1231/// `append_session`. Returns `Outcome<Appended>`.
1232#[derive(Debug, Serialize, Deserialize)]
1233pub struct AppendSessionArgs {
1234 pub actor: User,
1235 pub repo: RepoPath,
1236 pub number: u32,
1237 pub entries: Vec<NewSessionEntry>,
1238}
1239
1240#[derive(Debug, Serialize, Deserialize)]
1241pub struct Appended {
1242 pub count: u32,
1243}
1244
1245/// `start_review`: begins a review of a pull request by a g1t agent. Called
1246/// by the runner service, which starts the sandbox. Returns
1247/// `Outcome<ReviewJob>`.
1248#[derive(Debug, Serialize, Deserialize)]
1249#[serde(rename_all = "camelCase")]
1250pub struct StartReviewArgs {
1251 pub pull_id: String,
1252}
1253
1254/// What a sandbox needs to review a pull request.
1255#[derive(Debug, Serialize, Deserialize)]
1256#[serde(rename_all = "camelCase")]
1257pub struct ReviewJob {
1258 pub run_id: String,
1259 /// Lets the sandbox, and nothing else, report this review.
1260 pub token: String,
1261 /// The repository holding the commit: the fork, or the repository itself.
1262 pub source: RepoPath,
1263 pub commit: String,
1264 pub repo: RepoPath,
1265 pub default_branch: String,
1266 pub number: u32,
1267 pub title: String,
1268 pub description: String,
1269 /// The issue the pull request is for, which says what it should achieve.
1270 pub issue: Option<Issue>,
1271 /// Who opened the pull request, and so can read its source.
1272 pub author: User,
1273}
1274
1275/// A comment on one line, as a reviewing agent reports it.
1276#[derive(Debug, Serialize, Deserialize)]
1277pub struct ReviewComment {
1278 pub path: String,
1279 #[serde(default)]
1280 pub line: u32,
1281 pub body: String,
1282}
1283
1284/// `report_review`: the review a sandbox's agent wrote, or why it could not
1285/// write one. Returns `Outcome<bool>`.
1286#[derive(Debug, Serialize, Deserialize)]
1287#[serde(rename_all = "camelCase")]
1288pub struct ReportReviewArgs {
1289 pub run_id: String,
1290 pub token: String,
1291 #[serde(default)]
1292 pub verdict: Option<Verdict>,
1293 #[serde(default)]
1294 pub body: String,
1295 #[serde(default)]
1296 pub comments: Vec<ReviewComment>,
1297 /// The model that wrote it, by its public name.
1298 #[serde(default)]
1299 pub model: Option<String>,
1300 #[serde(default)]
1301 pub error: Option<String>,
1302}
1303
1304/// Lowercases, trims and de-duplicates labels, dropping empty ones.
1305/// Returns `None` if there are too many or one is too long.
1306pub fn normalize_labels(labels: &[String]) -> Option<Vec<String>> {
1307 const MAX_LABELS: usize = 10;
1308 const MAX_LABEL_CHARS: usize = 40;
1309 let mut normalized: Vec<String> = Vec::new();
1310 for label in labels {
1311 let label = label
1312 .split_whitespace()
1313 .collect::<Vec<_>>()
1314 .join(" ")
1315 .to_lowercase();
1316 if label.is_empty() || normalized.contains(&label) {
1317 continue;
1318 }
1319 if label.chars().count() > MAX_LABEL_CHARS {
1320 return None;
1321 }
1322 normalized.push(label);
1323 }
1324 (normalized.len() <= MAX_LABELS).then_some(normalized)
1325}
1326
1327#[cfg(test)]
1328mod tests {
1329 use super::normalize_labels;
1330
1331 fn labels(names: &[&str]) -> Vec<String> {
1332 names.iter().map(|name| (*name).to_owned()).collect()
1333 }
1334
1335 #[test]
1336 fn labels_are_lowercased_trimmed_and_unique() {
1337 assert_eq!(
1338 normalize_labels(&labels(&[" Bug ", "bug", "", "Good First Issue"])),
1339 Some(labels(&["bug", "good first issue"]))
1340 );
1341 }
1342
1343 #[test]
1344 fn too_long_or_too_many_labels_are_refused() {
1345 assert_eq!(normalize_labels(&["x".repeat(41)]), None);
1346 let many: Vec<String> = (0..11).map(|i| format!("label-{i}")).collect();
1347 assert_eq!(normalize_labels(&many), None);
1348 }
1349}
1350
1351
1352// --- Merge queue ----------------------------------------------------------
1353
1354/// Where a pull request in a merge queue stands.
1355#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1356#[serde(rename_all = "snake_case")]
1357pub enum QueueState {
1358 /// Waiting for its turn to be tested.
1359 Waiting,
1360 /// Its combined state is being built and checked.
1361 Testing,
1362 /// Its combined state passed; it lands once everything ahead has.
1363 Passed,
1364 /// Its combined state failed, or would not merge. It left the queue.
1365 Failed,
1366 /// On the default branch.
1367 Landed,
1368 /// Taken out of the queue by a person, or closed.
1369 Removed,
1370}
1371
1372impl QueueState {
1373 pub fn as_str(self) -> &'static str {
1374 match self {
1375 QueueState::Waiting => "waiting",
1376 QueueState::Testing => "testing",
1377 QueueState::Passed => "passed",
1378 QueueState::Failed => "failed",
1379 QueueState::Landed => "landed",
1380 QueueState::Removed => "removed",
1381 }
1382 }
1383
1384 /// Still in the queue.
1385 pub fn is_active(self) -> bool {
1386 matches!(
1387 self,
1388 QueueState::Waiting | QueueState::Testing | QueueState::Passed
1389 )
1390 }
1391}
1392
1393/// One pull request's place in a merge queue.
1394#[derive(Clone, Debug, Serialize, Deserialize)]
1395#[serde(rename_all = "camelCase")]
1396pub struct QueueEntry {
1397 pub id: String,
1398 pub number: u32,
1399 pub title: String,
1400 /// Who or what made the pull request, e.g. `g1t-agent`.
1401 pub agent: String,
1402 pub state: QueueState,
1403 /// The pull requests merged ahead of it in the state being tested, in
1404 /// queue order. Empty when it was tested on the default branch alone.
1405 pub ahead: Vec<u32>,
1406 /// The default branch's commit the tested state was built on.
1407 pub base_commit: Option<String>,
1408 /// The tested state: the default branch with everything ahead and this.
1409 pub combined_commit: Option<String>,
1410 /// Why it failed: a merge conflict or what could not be run.
1411 pub error: Option<String>,
1412 /// The checks run against the tested state.
1413 pub results: Vec<CheckResult>,
1414 /// Username of whoever merged it into the queue: a person, or `g1t`.
1415 pub enqueued_by: String,
1416 /// RFC 3339.
1417 pub created_at: String,
1418 /// RFC 3339. When it landed or left.
1419 pub finished_at: Option<String>,
1420}
1421
1422/// A repository's merge queue: what is in it, in order, and what recently
1423/// left it.
1424#[derive(Clone, Debug, Serialize, Deserialize)]
1425#[serde(rename_all = "camelCase")]
1426pub struct QueueView {
1427 /// Whether the repository merges through the queue.
1428 pub enabled: bool,
1429 pub active: Vec<QueueEntry>,
1430 /// Newest first.
1431 pub recent: Vec<QueueEntry>,
1432}
1433
1434/// `queue`: a repository's merge queue. Returns `Outcome<QueueView>`.
1435#[derive(Debug, Serialize, Deserialize)]
1436pub struct QueueArgs {
1437 pub repo: RepoPath,
1438 pub viewer: Viewer,
1439}
1440
1441/// `queue_build`: the next batch to test for a repository, if nothing is
1442/// being tested now. Returns `Vec<QueueJob>`, one per entry, each testing
1443/// the default branch with that entry and everything ahead of it.
1444#[derive(Debug, Serialize, Deserialize)]
1445#[serde(rename_all = "camelCase")]
1446pub struct QueueBuildArgs {
1447 pub repo_id: String,
1448}
1449
1450/// One pull request in a state being tested: where its change is.
1451#[derive(Clone, Debug, Serialize, Deserialize)]
1452#[serde(rename_all = "camelCase")]
1453pub struct QueueStackItem {
1454 pub number: u32,
1455 pub title: String,
1456 /// The repository holding the change: its fork, or the repository.
1457 pub source: RepoPath,
1458 /// The branch of `source` holding it.
1459 pub branch: String,
1460 pub commit: String,
1461}
1462
1463/// What a sandbox needs to build and check one combined state.
1464#[derive(Clone, Debug, Serialize, Deserialize)]
1465#[serde(rename_all = "camelCase")]
1466pub struct QueueJob {
1467 pub entry_id: String,
1468 /// Lets the sandbox, and nothing else, report this state's result.
1469 pub token: String,
1470 pub repo: RepoPath,
1471 pub default_branch: String,
1472 /// The default branch's commit to build on.
1473 pub base_commit: String,
1474 /// Where to push the tested state, in the repository itself.
1475 pub branch: String,
1476 /// The pull requests to merge in, in order; the last is the entry.
1477 pub stack: Vec<QueueStackItem>,
1478 /// Every acceptance check of every pull request in the stack.
1479 pub checks: Vec<String>,
1480 /// The checks of issues already completed: the default branch's
1481 /// contract. One that fails on the base alone is not held against the
1482 /// entry.
1483 #[serde(default)]
1484 pub contract_checks: Vec<String>,
1485 /// Who the sandbox acts as: a member who can push the tested state.
1486 pub actor: User,
1487}
1488
1489/// `report_queue`: a sandbox's result for one combined state. Returns
1490/// `Outcome<QueueState>`.
1491#[derive(Debug, Serialize, Deserialize)]
1492#[serde(rename_all = "camelCase")]
1493pub struct ReportQueueArgs {
1494 pub entry_id: String,
1495 pub token: String,
1496 #[serde(default)]
1497 pub combined_commit: Option<String>,
1498 #[serde(default)]
1499 pub results: Vec<CheckResult>,
1500 /// Set when the state could not be built or checked.
1501 #[serde(default)]
1502 pub error: Option<String>,
1503 /// For a merge conflict: the pull request whose change it collided with.
1504 #[serde(default)]
1505 pub conflict_with: Option<u32>,
1506 /// For a merge conflict: the files that conflicted.
1507 #[serde(default)]
1508 pub conflicts: Vec<String>,
1509}
1510
1511
1512/// `locate_pull`: where a pull request lives, by its id, for a tool that
1513/// knows only the fork it is working in (`g1t.sh/pulls/<id>`). Returns
1514/// `Outcome<LocatedPull>`; not found for anyone who cannot see it.
1515#[derive(Debug, Serialize, Deserialize)]
1516pub struct LocatePullArgs {
1517 pub id: String,
1518 pub viewer: Viewer,
1519}
1520
1521#[derive(Clone, Debug, Serialize, Deserialize)]
1522#[serde(rename_all = "camelCase")]
1523pub struct LocatedPull {
1524 pub repo: RepoPath,
1525 pub number: u32,
1526 pub title: String,
1527 pub status: PullStatus,
1528}
1529
1530// --- A person's work -------------------------------------------------------
1531
1532/// Issues or pull requests, on a person's profile.
1533#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1534#[serde(rename_all = "lowercase")]
1535pub enum AuthoredKind {
1536 Issue,
1537 Pull,
1538}
1539
1540/// The state filter on a person's work. `Closed` takes in merged pull
1541/// requests too; `Merged` is only those.
1542#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1543#[serde(rename_all = "lowercase")]
1544pub enum AuthoredState {
1545 Open,
1546 Closed,
1547 Merged,
1548}
1549
1550/// How a person's work is ordered.
1551#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
1552#[serde(rename_all = "lowercase")]
1553pub enum AuthoredSort {
1554 /// Newest first.
1555 #[default]
1556 Created,
1557 /// Most recently changed first.
1558 Updated,
1559 /// Oldest first.
1560 Oldest,
1561}
1562
1563/// The most items one `by_author` page holds.
1564pub const AUTHORED_PAGE: u32 = 25;
1565
1566/// `by_author`: the issues and pull requests a person opened, only on
1567/// repositories `viewer` may read, so a private title never reaches anyone
1568/// who could not open it. Returns `Outcome<Authored>`; not found for an
1569/// account that does not exist.
1570#[derive(Debug, Serialize, Deserialize)]
1571pub struct ByAuthorArgs {
1572 pub username: String,
1573 pub viewer: Viewer,
1574 #[serde(default)]
1575 pub kind: Option<AuthoredKind>,
1576 #[serde(default)]
1577 pub state: Option<AuthoredState>,
1578 /// Only work on this repository: `namespace/name`.
1579 #[serde(default)]
1580 pub repo: Option<String>,
1581 #[serde(default)]
1582 pub sort: AuthoredSort,
1583 /// The `next` of the page before, to read on from there.
1584 #[serde(default)]
1585 pub before: Option<String>,
1586 /// At most [`AUTHORED_PAGE`]; that when absent.
1587 #[serde(default)]
1588 pub limit: Option<u32>,
1589}
1590
1591/// One issue or pull request a person opened.
1592#[derive(Clone, Debug, Serialize, Deserialize)]
1593#[serde(rename_all = "camelCase")]
1594pub struct AuthoredItem {
1595 pub kind: AuthoredKind,
1596 pub repo: RepoPath,
1597 pub number: u32,
1598 pub title: String,
1599 /// Open or closed; a merged pull request is closed.
1600 pub state: State,
1601 /// A pull request's own status.
1602 pub status: Option<PullStatus>,
1603 /// Why an issue was closed.
1604 pub reason: Option<IssueReason>,
1605 pub draft: bool,
1606 pub merged: bool,
1607 /// RFC 3339.
1608 pub created_at: String,
1609 /// RFC 3339.
1610 pub updated_at: String,
1611 /// When a pull request was merged. RFC 3339.
1612 pub merged_at: Option<String>,
1613}
1614
1615/// What a person has done, as far as the viewer may see.
1616#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1617#[serde(rename_all = "camelCase")]
1618pub struct AuthoredCounts {
1619 pub pulls_merged: u32,
1620 pub pulls_open: u32,
1621 pub pulls: u32,
1622 pub issues: u32,
1623 pub issues_open: u32,
1624}
1625
1626/// A repository a person has opened work on, with how much.
1627#[derive(Clone, Debug, Serialize, Deserialize)]
1628pub struct AuthoredRepo {
1629 pub repo: RepoPath,
1630 pub count: u32,
1631}
1632
1633/// A page of a person's work.
1634#[derive(Clone, Debug, Default, Serialize, Deserialize)]
1635#[serde(rename_all = "camelCase")]
1636pub struct Authored {
1637 pub items: Vec<AuthoredItem>,
1638 /// Pass as `before` for the next page; null on the last.
1639 pub next: Option<String>,
1640 /// Over every repository the viewer may read, whatever the filters.
1641 pub counts: AuthoredCounts,
1642 /// Those repositories, most work first.
1643 pub repos: Vec<AuthoredRepo>,
1644}