Trait ReviewProvider 

pub trait ReviewProvider {
    // Required methods
    fn review_for_branch(&self, branch: &str) -> Result<Option<ReviewRequest>>;
    fn review_for_branch_including_closed(
        &self,
        branch: &str,
    ) -> Result<Option<ReviewRequest>>;
    fn create_review(
        &self,
        branch: &str,
        base: &str,
        draft: bool,
        title: Option<&str>,
    ) -> Result<String>;
    fn update_review_base(
        &self,
        review: &ReviewRequest,
        base: &str,
    ) -> Result<String>;
    fn update_review_title(
        &self,
        review: &ReviewRequest,
        title: &str,
    ) -> Result<String>;
    fn review_body(&self, review: &ReviewRequest) -> Result<String>;
    fn update_review_body(
        &self,
        review: &ReviewRequest,
        body: &str,
    ) -> Result<String>;
    fn merge_review(
        &self,
        review: &ReviewRequest,
        strategy: &str,
        auto: bool,
    ) -> Result<String>;
    fn merge_blocker(&self, review: &ReviewRequest) -> Result<MergeBlocker>;
    fn wait_for_checks(&self, review: &ReviewRequest) -> Result<WaitOutcome>;
    fn open_reviews(&self) -> Result<Vec<ReviewRequest>>;
    fn mark_ready(&self, review: &ReviewRequest) -> Result<String>;
    fn close_review(
        &self,
        review: &ReviewRequest,
        delete_branch: bool,
    ) -> Result<String>;
    fn open_review(&self, review: &ReviewRequest) -> Result<String>;

    // Provided methods
    fn base_gap(
        &self,
        review: &ReviewRequest,
        parent: &str,
    ) -> Result<Option<BaseGap>> { ... }
    fn review_state(
        &self,
        review: &ReviewRequest,
    ) -> Result<Option<ReviewState>> { ... }
    fn native_stack_for(&self, branch: &str) -> Result<Option<NativeStack>> { ... }
    fn register_stack(
        &self,
        reviews: &[String],
        existing: Option<&NativeStack>,
    ) -> Result<Option<String>> { ... }
    fn registers_stacks(&self) -> bool { ... }
    fn native_stacks_covering(
        &self,
        branches: &[String],
    ) -> Result<Vec<NativeStack>> { ... }
    fn unstack_reviews(&self, stack: &NativeStack) -> Result<Option<String>> { ... }
    fn annotate_branches(
        &self,
        branches: &[String],
        detail: bool,
    ) -> Result<BTreeMap<String, ReviewAnnotation>> { ... }
    fn annotate_review(
        &self,
        review: &ReviewRequest,
        detail: bool,
    ) -> Result<ReviewAnnotation> { ... }
    fn check_status(&self, _review: &ReviewRequest) -> Result<CheckStatus> { ... }
    fn review_summary(&self, _review: &ReviewRequest) -> Result<ReviewSummary> { ... }
    fn request_reviewers(
        &self,
        _review: &ReviewRequest,
        _reviewers: &[String],
    ) -> Result<String> { ... }
    fn enqueued_branches(
        &self,
        _branches: &[String],
    ) -> Result<BTreeSet<String>> { ... }
}

Required Methods

fn review_for_branch(&self, branch: &str) -> Result<Option<ReviewRequest>>

fn review_for_branch_including_closed( &self, branch: &str, ) -> Result<Option<ReviewRequest>>

Like review_for_branch, but also finds closed reviews. Kept separate so flows that act on a review (submit, sync, cleanup) never mistake a dead review for a live one; only the stack-notes ledger wants closed state, to restyle the entry rather than drop it.

fn create_review( &self, branch: &str, base: &str, draft: bool, title: Option<&str>, ) -> Result<String>

Open a review for the branch; with draft, as a draft. title sets the review’s title, defaulting to the branch tip’s commit subject.

fn update_review_base( &self, review: &ReviewRequest, base: &str, ) -> Result<String>

fn update_review_title( &self, review: &ReviewRequest, title: &str, ) -> Result<String>

Retitle an existing review. Platforms that encode draft state in the title (Gitea’s WIP:, GitLab’s Draft:) re-apply their prefix, so a retitle never readies a draft.

fn review_body(&self, review: &ReviewRequest) -> Result<String>

fn update_review_body( &self, review: &ReviewRequest, body: &str, ) -> Result<String>

fn merge_review( &self, review: &ReviewRequest, strategy: &str, auto: bool, ) -> Result<String>

Merge the review with the given strategy: squash, rebase, or merge. With auto, schedule the merge for when required checks pass instead of merging now.

fn merge_blocker(&self, review: &ReviewRequest) -> Result<MergeBlocker>

Why the platform won’t merge the review right now, read from its structured status. Consulted after a merge is rejected to explain it without parsing the CLI’s error text.

fn wait_for_checks(&self, review: &ReviewRequest) -> Result<WaitOutcome>

Block until the review’s checks settle, returning how the wait ended: checks passed (or there are none), one failed, or the review merged out-of-band while we waited.

fn open_reviews(&self) -> Result<Vec<ReviewRequest>>

Every open review, in one call - for annotating the stack with review numbers (and CI status) without a lookup per branch.

fn mark_ready(&self, review: &ReviewRequest) -> Result<String>

Mark a draft review as ready for review.

fn close_review( &self, review: &ReviewRequest, delete_branch: bool, ) -> Result<String>

Close the review without merging, deleting its source branch when delete_branch. Used to retire a review superseded by a branch rename.

fn open_review(&self, review: &ReviewRequest) -> Result<String>

Open the review in the user’s browser.

Provided Methods

fn base_gap( &self, review: &ReviewRequest, parent: &str, ) -> Result<Option<BaseGap>>

What will close a gap between this review’s base and parent, the local parent git-stk records - or None when the review is in no platform stack, in which case an ordinary retarget closes it.

One question rather than two, because every caller needs all three answers: those that would retarget stand down for BaseGap::Platform, and those that report a disagreement need to name a different remedy for each of the other two.

Defaults to None, and errs that way, because the two mistakes are not equally bad. Answering None wrongly means attempting a retarget the platform refuses: a loud, recoverable error, and update_review_base checks again itself. Answering BaseGap::Platform wrongly means skipping a retarget that was needed - in cleanup the layer then still points at a branch about to be deleted, and a platform that auto-closes a review whose base disappears takes the review with it, comments and approvals included, silently.

fn review_state(&self, review: &ReviewRequest) -> Result<Option<ReviewState>>

A carried-forward ledger row’s current state, re-fetched by id after its branch has left the local stack. Nothing else re-queries such a row, so one that merged or closed since it was last recorded keeps rendering as open in the overview without this. Default None: a provider that cannot resolve a review by id alone leaves the recorded state untouched, and the caller treats any error as “leave it as-is” (best-effort refresh).

fn native_stack_for(&self, branch: &str) -> Result<Option<NativeStack>>

The platform’s own record of the stack branch belongs to, when it keeps one. An authoritative ordering that outlives local metadata, so repair can prefer it to guessing from ancestry.

Default None: no platform but GitHub records stacks. Not gated on stk.githubStacks - that setting says whether git-stk registers one, and a stack can exist without it having done so. An error here is the caller’s to treat as “no stack” - for the callers that use it as a hint. A caller for which the answer is the command must ask differently, or it will report “no stack” for a failed lookup.

fn register_stack( &self, reviews: &[String], existing: Option<&NativeStack>, ) -> Result<Option<String>>

Record reviews (bottom first) as a stack on the platform, extending existing when the stack is already there and the new reviews sit on top of it. Returns a line describing what happened, or None when there was nothing to do.

Default None: only GitHub keeps stacks, and only when stk.githubStacks is on. Registering is presentation - the stack map and parallel review - so a failure here is reported, never fatal to a submit whose reviews already exist.

fn registers_stacks(&self) -> bool

Whether this provider would register a stack at all - the provider keeps stacks, and the user has asked for it.

Asked before anything is fetched, and by the dry run and the real run alike, so the two decline for the same reason rather than one promising a stack the other declines - and so a provider that keeps no stacks spends no lookups discovering that.

Default false: only GitHub keeps stacks.

fn native_stacks_covering( &self, branches: &[String], ) -> Result<Vec<NativeStack>>

Every platform stack covering any of branches, for a caller where the answer is the command rather than a hint: a lookup failure is returned instead of read as “no stack”.

All of them, not the first - two stacks can partition one local line, and dissolving only the one you happened to find would report success while leaving the rest of the line blocked.

fn unstack_reviews(&self, stack: &NativeStack) -> Result<Option<String>>

Dissolve stack on the platform, leaving its reviews open and standalone. Merged reviews stay in it - the platform keeps that history. Returns a line describing what happened.

Default None: only GitHub keeps stacks. Unlike registering, this is not gated on stk.githubStacks - undoing something must not require the setting that created it to still be on.

fn annotate_branches( &self, branches: &[String], detail: bool, ) -> Result<BTreeMap<String, ReviewAnnotation>>

Review annotations (id, CI dot, queue state, and - with detail - review tallies) for the given branches, in as few calls as the provider allows. The default is the generic per-branch path; a provider can override to batch (GitHub folds it into a single GraphQL query). Only branches with an open review appear in the result.

fn annotate_review( &self, review: &ReviewRequest, detail: bool, ) -> Result<ReviewAnnotation>

The same annotation for a single review the caller already holds - status, which asks about one branch rather than a stack.

Separate from ReviewProvider::annotate_branches because the two want opposite things. Listing every open review amortizes across a whole stack but is pure overhead for one branch, and the generic listing is what most providers do. The default therefore asks per review; GitHub overrides it with the one batched query it already makes for list, which is also the only source of a stack position.

fn check_status(&self, _review: &ReviewRequest) -> Result<CheckStatus>

The CI check rollup for the review’s head, for the list/status dot. Best-effort display data: the default is CheckStatus::None (no dot), which is also the right answer for a provider that cannot report it.

fn review_summary(&self, _review: &ReviewRequest) -> Result<ReviewSummary>

The review’s latest-review tallies, for list --reviews. Fetched per branch only when the flag is set; the default is an empty summary.

fn request_reviewers( &self, _review: &ReviewRequest, _reviewers: &[String], ) -> Result<String>

Request reviews from the given users or teams on the review, additively (anyone already requested stays). Team reviewers use the provider’s own form (GitHub/Gitea org/team). The default errors, so a provider without reviewer support surfaces that rather than dropping the request.

fn enqueued_branches(&self, _branches: &[String]) -> Result<BTreeSet<String>>

Of branches, those whose review is locked by a merge queue (GitHub) or merge train (GitLab): they must be neither rebased nor force-pushed. Rebasing would diverge from the frozen remote tip; a push is rejected outright (GitHub locks the branch) or silently drops the review from the queue (GitLab does not lock it). The default is empty - for providers without a queue, and as the safe degradation when the lookup itself fails (the reactive push-rejection net in git is the backstop).

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors