Files
2026-11-13 03:51:42 +11:00

187 lines
6.2 KiB
Go

package forge
import (
"context"
"errors"
"fmt"
"io"
"strings"
"time"
)
// ErrBlockedByDependencies is wrapped by a forge's CloseIssue when the forge
// refuses to close an issue that still has open dependencies.
var ErrBlockedByDependencies = errors.New("forge refused: open dependencies")
// Config is what the host hands a forge extension once, after launch.
type Config struct {
Host string
Token string
Settings map[string]string
}
// Issue is an issue (never a pull request).
type Issue struct {
Number int
Title string
Body string
Labels []string
// Author is the login that opened the issue.
Author string
}
// RepoRef identifies one repository on a forge.
type RepoRef struct {
Owner string
Repo string
}
// Forge is the capability every forge extension has.
type Forge interface {
AssignedIssues(ctx context.Context, owner, repo, assignee string) ([]Issue, error)
IssuesWithLabel(ctx context.Context, owner, repo, label string) ([]Issue, error)
Comment(ctx context.Context, owner, repo string, number int, body string) (int64, error)
// CreateIssue opens an issue with title, body and optional labels,
// returning its number.
CreateIssue(ctx context.Context, owner, repo, title, body string, labels []string) (int, error)
CloseIssue(ctx context.Context, owner, repo string, number int, comment string) error
React(ctx context.Context, owner, repo string, number int, reaction string) error
// SetStateLabel makes label the issue's only state label, removing any
// other label in knownLabels first. An empty label clears them.
SetStateLabel(ctx context.Context, owner, repo string, number int, label string, knownLabels []string)
CreatePR(ctx context.Context, owner, repo, title, head, base, body string) (int, error)
// PRState is "open", "merged" or "closed".
PRState(ctx context.Context, owner, repo string, number int) (string, error)
// ClosePR closes a pull request without merging, with an optional final
// comment.
ClosePR(ctx context.Context, owner, repo string, number int, comment string) error
// MergePR merges a pull request with the forge's default method.
MergePR(ctx context.Context, owner, repo string, number int) error
// AcceptInvitations accepts pending repository invitations, but only to
// the given repositories: an invitation to anything else is left
// pending, so a stranger cannot add the forge's account to a repository
// the operator never configured.
AcceptInvitations(ctx context.Context, repos []RepoRef) error
VerifyPush(ctx context.Context, owner, repo string) error
LinkBranch(ctx context.Context, owner, repo string, issueNumber int, branch string) error
}
// PullRequest summarises an existing pull request.
type PullRequest struct {
Number int
Title string
Body string
HeadRef string
BaseRef string
HeadSHA string
BaseSHA string
State string
}
// PullRequestReader, PullRequestDiffReader, RepoArchiveReader, ReviewReader,
// ReviewCommentWriter is optional: an extension implements
// the ones its forge supports and the host sees the rest as unsupported.
type PullRequestReader interface {
GetPullRequest(ctx context.Context, owner, repo string, number int) (PullRequest, error)
}
type PullRequestDiffReader interface {
GetPullRequestDiff(ctx context.Context, owner, repo string, number int) (string, error)
}
type RepoArchiveReader interface {
GetRepoArchive(ctx context.Context, owner, repo, ref string) (io.ReadCloser, error)
}
// Review states, normalised across forges.
const (
ReviewStateApproved = "approved"
ReviewStateRequestedChanges = "requested_changes"
ReviewStateCommented = "commented"
ReviewStateDismissed = "dismissed"
)
type Review struct {
ID int64
Author string
State string
Body string
SubmittedAt time.Time
}
type ReviewComment struct {
ID int64
ReviewID int64
Author string
Body string
Path string
Line int
InReplyTo int64
CreatedAt time.Time
}
type ReviewReader interface {
ListReviews(ctx context.Context, owner, repo string, number int, sinceID int64) ([]Review, error)
ListReviewComments(ctx context.Context, owner, repo string, number int, sinceID int64) ([]ReviewComment, error)
ReplyToReview(ctx context.Context, owner, repo string, number int, commentID int64, body string) error
}
// WriteAccessChecker is optional: an extension implements it so archie can
// tell collaborators from strangers before forge text reaches an agent.
type WriteAccessChecker interface {
// HasWriteAccess reports whether user may push to the repository.
HasWriteAccess(ctx context.Context, owner, repo, user string) (bool, error)
}
type InlineReviewComment struct {
Path string
Line int
Body string
}
// Review events a submission may carry.
const (
ReviewEventComment = "COMMENT"
ReviewEventRequestChanges = "REQUEST_CHANGES"
)
// ReviewSubmission is one submitted PR review. Body lists findings that have
// no line anchor.
type ReviewSubmission struct {
Event string
Body string
Comments []InlineReviewComment
}
type ReviewCommentWriter interface {
CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, review ReviewSubmission) error
}
// ReviewHeadDrift is an error when head is no longer reviewedHeadSHA; an empty
// reviewedHeadSHA skips the check.
func ReviewHeadDrift(owner, repo string, number int, head, reviewedHeadSHA string) error {
if reviewedHeadSHA == "" || strings.EqualFold(head, reviewedHeadSHA) {
return nil
}
return fmt.Errorf(
"pull request %s/%s#%d has moved off the reviewed revision (%s): head is now %s, so the line-anchored comments would land on lines they were not measured against",
owner, repo, number, reviewedHeadSHA, head,
)
}
// GitCredential is a short-lived git credential for one repository and the
// identity commits through it carry.
type GitCredential struct {
Username string
Token string
ExpiresAt time.Time
CommitName string
CommitEmail string
}
// GitCredentialIssuer mints per-repository git credentials, such as an app
// installation token. A forge without it has git use the configured token.
type GitCredentialIssuer interface {
GitCredential(ctx context.Context, owner, repo string) (GitCredential, error)
}