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) }