187 lines
6.2 KiB
Go
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)
|
|
}
|