// Package forge defines the interface archie uses to interact with a git // host -- polling issues, managing labels, opening PRs, and reacting to // comments. GitHub and Gitea are the supported implementations. package forge import ( "context" "fmt" "log/slog" "strings" "time" ) // New creates a Forge implementation for the given type. func New(forgeType, token, host string, log *slog.Logger) (Forge, error) { switch forgeType { case "github": return NewGitHub(token, host, log) case "gitea": return NewGitea(token, host, log) case "none", "off", "disabled", "": return NewNoop(log), nil default: return nil, fmt.Errorf("unsupported forge type %q (want github, gitea, or none)", forgeType) } } // Issue is a forge-neutral representation of an issue (not a PR). type Issue struct { Number int Title string Body string Labels []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) // 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). SetStateLabel(ctx context.Context, owner, repo string, number int, label string, knownLabels []string) } // 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) } // 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) } // RepoForge is repository-level operations. type RepoForge interface { // AcceptInvitations auto-accepts pending repository invitations. AcceptInvitations(ctx context.Context) 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. It is what lets a // comment be collected into its review's remediation unit instead of // starting one of its own (pr-review-remediation.md decision 5); a // standalone comment carries 0. GitHub carries it on the comment; // Gitea's flat comment list is walked per review, so the mapping comes // from the walk. ReviewID int64 Author string Body string Path string Line int InReplyTo int64 CreatedAt time.Time } // PullRequestReviewReader reads review activity on an existing PR. Forge // implementations that cannot read reviews (the noop forge) do not implement // it; callers type-assert and refuse when the capability is absent. // // sinceID is the dedup cursor: only entries with ID > sinceID are returned, // so a poller and a webhook delivery of the same comment collapse on the same // ID (the TaskEnvelope.IdempotencyKey pattern applied to reviews). 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 } // 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 } // ReviewCommentWriter posts line-anchored review comments on an open pull // request. Forge implementations that cannot (the noop forge) do not implement // it; callers type-assert and degrade to the PR-body list rather than faking it. // // The set travels in one call because that is Gitea's native shape (a single // COMMENT-state review carrying many comments); GitHub loops internally. Each // implementation reads the pull request's current head itself and anchors the // comments to it, but only after checking it against reviewedHeadSHA -- the // revision the caller's line numbers were measured on. A line number that // outlives its revision does not fail loudly at the forge: it attaches to // whatever is on that line now, so the set is refused once the head has moved. // An empty reviewedHeadSHA means the caller could not measure one, and posts // unanchored by revision rather than dropping every finding. type ReviewCommentWriter interface { CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error } // reviewHeadDrift is the rule ReviewCommentWriter's implementations share: a // line-anchored comment set may be posted only while the pull request's head is // still the revision those line numbers were measured on. It returns nil when // there is nothing to refuse, including when the caller could not measure a // revision at all (reviewedHeadSHA == "") -- posting unverified is the // pre-existing behaviour, and is strictly better than dropping every finding. // // The check lives here rather than in each implementation because the danger is // identical on both: GitHub and Gitea accept a line number against the current // head and anchor it to whatever now occupies that line, so a stale anchor does // not fail loudly -- it misinforms. 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, ) } // normalizeReviewState maps a GitHub review state string onto the neutral // ReviewState* constants. Unknown states pass through lowercased. func normalizeReviewState(s string) string { switch s { case "APPROVED": return ReviewStateApproved case "CHANGES_REQUESTED": return ReviewStateRequestedChanges case "COMMENTED": return ReviewStateCommented case "DISMISSED": return ReviewStateDismissed default: return strings.ToLower(s) } }