// Package forge defines the interface archie uses to interact with a git // host: polling issues, managing labels, opening PRs, and reacting to // comments. Forge extensions implement it over the forge.v1 surface. package forge import ( "context" "errors" "fmt" "io" "log/slog" "time" ) // ErrBlockedByDependencies is returned by CloseIssue when the forge refuses to // close an issue that still has open dependencies. Callers match it with // errors.Is; the forge's own message stays in the error text. var ErrBlockedByDependencies = errors.New("forge refused: open dependencies") // Issue is a forge-neutral representation of an issue (not a PR). type Issue struct { Number int Title string Body string Labels []string // Author is the login that opened the issue. Author string } // Forge is the interface for interacting with a git host. type Forge interface { IssueForge PullRequestForge RepoForge } // IssueForge is issue-level operations. type IssueForge interface { // AssignedIssues returns open issues assigned to the given user, // excluding PRs. AssignedIssues(ctx context.Context, owner, repo, assignee string) ([]Issue, error) // IssuesWithLabel returns open issues matching the given label, // excluding PRs. IssuesWithLabel(ctx context.Context, owner, repo, label string) ([]Issue, error) // Comment posts an issue (or PR) comment and returns its id. 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 closes an issue with an optional final comment. CloseIssue(ctx context.Context, owner, repo string, number int, comment string) error // React adds an emoji reaction to an issue. 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 that appears in knownLabels first. An empty label clears // all state labels (terminal states). A failed label change is returned // so the caller can decide what to do about it. SetStateLabel(ctx context.Context, owner, repo string, number int, label string, knownLabels []string) error } // PullRequestForge is pull-request-level operations. type PullRequestForge interface { // CreatePR opens a pull request and returns its number. CreatePR(ctx context.Context, owner, repo, title, head, base, body string) (int, error) // PRState returns "open", "merged", or "closed" for a PR. 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 } // PullRequest is a forge-neutral summary of an existing pull request, // carrying the inputs the operator-triggered reviewer needs: its identity, // head/base refs and SHAs, and the title/body that serve as the review's // issue text. type PullRequest struct { Number int Title string Body string HeadRef string BaseRef string HeadSHA string BaseSHA string State string // "open", "merged", or "closed" } // PullRequestReader fetches an existing pull request's metadata. Forge // implementations that cannot read PRs (the noop forge) do not implement it; // callers type-assert and refuse review when the capability is absent. type PullRequestReader interface { GetPullRequest(ctx context.Context, owner, repo string, number int) (PullRequest, error) } // PullRequestDiffReader fetches a pull request's unified diff over the // forge's HTTP API. Implementations that cannot read PRs do not implement // it, matching PullRequestReader. type PullRequestDiffReader interface { GetPullRequestDiff(ctx context.Context, owner, repo string, number int) (string, error) } // RepoArchiveReader fetches a gzipped tar archive of a repository at a ref // over the forge's HTTP API, with no git-level credential involved: the // caller reads the returned stream and closes it. Implementations that // cannot read repository contents do not implement it. type RepoArchiveReader interface { GetRepoArchive(ctx context.Context, owner, repo, ref string) (io.ReadCloser, error) } // RepoRef identifies one repository on a forge. type RepoRef struct { Owner string Repo string } // RepoForge is repository-level operations. type RepoForge interface { // AcceptInvitations accepts pending repository invitations, but only // to the given repositories: an invitation to anything else is left // pending, so a stranger cannot add archie's account to a repository // the operator never configured. AcceptInvitations(ctx context.Context, repos []RepoRef) error // VerifyPush confirms the token can push to the repo. VerifyPush(ctx context.Context, owner, repo string) error // LinkBranch associates a branch with an issue so Gitea shows the // development link in the issue sidebar. LinkBranch(ctx context.Context, owner, repo string, issueNumber int, branch string) error } // ReviewState values for Review.State, normalised across forges. const ( ReviewStateApproved = "approved" ReviewStateRequestedChanges = "requested_changes" ReviewStateCommented = "commented" ReviewStateDismissed = "dismissed" ) // Review is a forge-neutral review of an existing PR: an approval, a // request-changes, a plain comment, or a dismissal. type Review struct { ID int64 Author string State string // one of the ReviewState* constants Body string // the review's own top-level summary; empty for a bare verdict SubmittedAt time.Time } // ReviewComment is a forge-neutral review comment on an existing PR. // Line is a location hint, not authoritative: the remediation agent reads // the whole file. InReplyTo is the parent comment ID on GitHub; Gitea's // inline comments are flat under a review, so it is 0 there. type ReviewComment struct { ID int64 // ReviewID is the review this comment belongs to; 0 for a standalone comment. ReviewID int64 Author string Body string Path string Line int InReplyTo int64 CreatedAt time.Time } // PullRequestReviewReader reads review activity on a PR newer than sinceID. type PullRequestReviewReader 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 posts a reply to an existing review comment (commentID). // A summary for a whole review (e.g. "requested changes" addressed) is a // plain PR comment via Forge.Comment, not this method. ReplyToReview(ctx context.Context, owner, repo string, number int, commentID int64, body string) error } // WriteAccessChecker reports whether a user may write to a repository. Forge // text from anyone else is untrusted and never reaches an agent as an // instruction. type WriteAccessChecker interface { HasWriteAccess(ctx context.Context, owner, repo, user string) (bool, error) } // WriterIssues keeps the issues opened by users with write access: anyone can // open an issue on a public repository, and agents act on what they read. A // forge that cannot answer fails closed, returning an error and no issues. func WriterIssues(ctx context.Context, log *slog.Logger, f IssueForge, owner, repo string, issues []Issue) ([]Issue, error) { checker, ok := f.(WriteAccessChecker) if !ok { return nil, errors.New("forge cannot check write access") } known := map[string]bool{} out := issues[:0:0] for _, is := range issues { allowed, seen := known[is.Author] if !seen { var err error if allowed, err = checker.HasWriteAccess(ctx, owner, repo, is.Author); err != nil { return nil, fmt.Errorf("check write access for %s: %w", is.Author, err) } known[is.Author] = allowed } if allowed { out = append(out, is) continue } log.WarnContext(ctx, "dropped issue from author without write access", "repo", owner+"/"+repo, "issue", is.Number, "author", is.Author) } return out, nil } // InlineReviewComment is one line-anchored comment to post on a PR: the file, // the line in the reviewed commit's version of it, and the body -- which may // carry a fenced suggestion block the author can apply in one click. type InlineReviewComment struct { Path string Line int Body string } // ReviewSubmission is one submitted PR review. Event is COMMENT or REQUEST_CHANGES; // empty means COMMENT. Body carries findings that have no line anchor. type ReviewSubmission struct { Event string Body string Comments []InlineReviewComment } // ReviewCommentWriter submits one review on a PR, refusing // when the head has moved past reviewedHeadSHA. Empty reviewedHeadSHA skips // the check. type ReviewCommentWriter interface { CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, review ReviewSubmission) error } // 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 is a forge that mints per-repository git credentials, // such as an app installation token. It returns errors.ErrUnsupported when // git should use the connection's stored token. type GitCredentialIssuer interface { GitCredential(ctx context.Context, owner, repo string) (GitCredential, error) }