Files
archie/internal/forge/github.go
T
sam 8faa0f6a30 feat(daemon,forge): the review-reaction producers
Sequencing steps 6 and 7 of pr-review-remediation.md: the consumer
landed in 052e350b, and these are the two sources that feed it.

Webhook (decision 2, low latency): the GitHub receiver decodes
pull_request_review and pull_request_review_comment events behind the
existing HMAC verification and publishes the same typed reaction the
poller produces, keyed source-independently so PublishUnique collapses
the two sources. Only submitted/created carry a verdict to remediate;
edited and dismissed are acknowledged. Reaction deliveries are
rate-limited per source (decision 6's 'add when the receiver gains a
second event family'), and the reaction path carries no dispatch
predicate -- eligibility is the consumer's owned-PR lookup.

Poll (both forges, the no-webhook backstop): one shared scan over all
pr_open tasks, each with the forge client its own identity owns
(reconcilePRs's shape), listing reviews and comments since per-task
persisted high-water marks and skipping the owning identity's bot user
(decision 5's own-comment exclusion, which the poll is positioned to
make identity-correct).

The cursors are two, not one: review IDs and comment IDs are independent
forge sequences, and a combined high-water mark would silently skip
reviews once a larger comment ID landed. watch_comment_id -- dead since
the comment-watch design it was created for never shipped -- carries the
comment cursor; review_cursor is a new presence-gated migrator column,
and SetReviewCursors is its guarded RPC (pr_open only, so cursors never
move under a run that owns the task). forge.ReviewComment gains ReviewID
so a comment is collectable into its review's unit (decision 5) on both
forges, and forge.Review gains Body so poll-delivered reviews carry
their summary.

Note: the store/proto/facade half of this work landed early in a65eae24
under a release session's message -- a shared-checkout collision, kept
rather than rewritten; that commit carries the review_cursor migration
and the SetReviewCursors contract, this one carries the producers.
2026-09-23 12:41:53 +10:00

438 lines
14 KiB
Go

// Package forge wraps the GitHub API surface archied needs: polling
// labelled issues, accepting collaborator invitations, commenting, and
// opening pull requests. Gitea support later lands as a second
// implementation behind the same methods.
package forge
import (
"context"
"errors"
"fmt"
"log/slog"
"strings"
"sync"
"github.com/google/go-github/v78/github"
)
// GitHubClient implements Forge against the GitHub API.
type GitHubClient struct {
gh *github.Client
log *slog.Logger
labelMu sync.Mutex
labelsEnsured map[string]bool
}
// NewGitHub creates a GitHub-backed Forge implementation. Non-github.com
// hosts are configured using GitHub Enterprise's API and upload URL conventions.
func NewGitHub(token, host string, log *slog.Logger) (Forge, error) {
client := github.NewClient(nil)
if strings.TrimRight(host, "/") != "https://github.com" {
var err error
client, err = client.WithEnterpriseURLs(host, host)
if err != nil {
return nil, fmt.Errorf("configure GitHub host %q: %w", host, err)
}
}
return &GitHubClient{gh: client.WithAuthToken(token), log: log}, nil
}
// AcceptInvitations auto-accepts pending repository invitations so
// adding archie as a collaborator is all a human has to do.
func (c *GitHubClient) AcceptInvitations(ctx context.Context) error {
invites, _, err := c.gh.Users.ListInvitations(ctx, nil)
if err != nil {
return fmt.Errorf("list invitations: %w", err)
}
for _, inv := range invites {
if _, err := c.gh.Users.AcceptInvitation(ctx, inv.GetID()); err != nil {
c.log.Warn("accept invitation failed", "repo", inv.GetRepo().GetFullName(), "err", err)
continue
}
c.log.Info("accepted repository invitation", "repo", inv.GetRepo().GetFullName())
}
return nil
}
// AssignedIssues returns open issues assigned to the given user,
// excluding PRs. Assigning an issue to the bot is how work is handed to
// archie (tink-bot style); labels only influence workflow routing.
func (c *GitHubClient) AssignedIssues(ctx context.Context, owner, repo, assignee string) ([]Issue, error) {
var out []Issue
opts := &github.IssueListByRepoOptions{
State: "open",
Assignee: assignee,
ListOptions: github.ListOptions{PerPage: 50},
}
for {
issues, resp, err := c.gh.Issues.ListByRepo(ctx, owner, repo, opts)
if err != nil {
return nil, fmt.Errorf("list issues %s/%s: %w", owner, repo, err)
}
for _, is := range issues {
if !is.IsPullRequest() {
out = append(out, Issue{
Number: is.GetNumber(),
Title: is.GetTitle(),
Body: is.GetBody(),
Labels: labelNames(is),
})
}
}
if resp.NextPage == 0 {
break
}
opts.ListOptions.Page = resp.NextPage
}
return out, nil
}
// labelNames extracts label names without flattening them, preserving
// valid label names that contain commas or leading/trailing whitespace.
func labelNames(is *github.Issue) []string {
var names []string
for _, l := range is.Labels {
names = append(names, l.GetName())
}
return names
}
// IssuesWithLabel returns open issues matching the given label, excluding
// PRs. Used when Dispatch.Trigger is "label" or "either" -- no assignee
// required, just the label.
func (c *GitHubClient) IssuesWithLabel(ctx context.Context, owner, repo, label string) ([]Issue, error) {
var out []Issue
opts := &github.IssueListByRepoOptions{
State: "open",
Labels: []string{label},
ListOptions: github.ListOptions{PerPage: 50},
}
for {
issues, resp, err := c.gh.Issues.ListByRepo(ctx, owner, repo, opts)
if err != nil {
return nil, fmt.Errorf("list issues %s/%s: %w", owner, repo, err)
}
for _, is := range issues {
if !is.IsPullRequest() {
out = append(out, Issue{
Number: is.GetNumber(),
Title: is.GetTitle(),
Body: is.GetBody(),
Labels: labelNames(is),
})
}
}
if resp.NextPage == 0 {
break
}
opts.ListOptions.Page = resp.NextPage
}
return out, nil
}
// Comment posts an issue (or PR) comment and returns its id, so a
// workflow can watch for replies that come after it.
func (c *GitHubClient) Comment(ctx context.Context, owner, repo string, number int, body string) (int64, error) {
cm, _, err := c.gh.Issues.CreateComment(ctx, owner, repo, number,
&github.IssueComment{Body: new(body)})
if err != nil {
return 0, err
}
return cm.GetID(), nil
}
// CreatePR opens a pull request and returns its number.
func (c *GitHubClient) CreatePR(ctx context.Context, owner, repo, title, head, base, body string) (int, error) {
pr, _, err := c.gh.PullRequests.Create(ctx, owner, repo, &github.NewPullRequest{
Title: new(title),
Head: new(head),
Base: new(base),
Body: new(body),
})
if err != nil {
return 0, fmt.Errorf("create PR %s/%s: %w", owner, repo, err)
}
return pr.GetNumber(), nil
}
// PRState returns "open", "merged", or "closed" for a PR.
func (c *GitHubClient) PRState(ctx context.Context, owner, repo string, number int) (string, error) {
pr, _, err := c.gh.PullRequests.Get(ctx, owner, repo, number)
if err != nil {
return "", err
}
if pr.GetMerged() {
return "merged", nil
}
return pr.GetState(), nil
}
// GetPullRequest returns the forge-neutral metadata for an existing PR.
func (c *GitHubClient) GetPullRequest(ctx context.Context, owner, repo string, number int) (PullRequest, error) {
pr, _, err := c.gh.PullRequests.Get(ctx, owner, repo, number)
if err != nil {
return PullRequest{}, fmt.Errorf("get pull request %s/%s#%d: %w", owner, repo, number, err)
}
state := pr.GetState()
if pr.GetMerged() {
state = "merged"
}
return PullRequest{
Number: pr.GetNumber(),
Title: pr.GetTitle(),
Body: pr.GetBody(),
HeadRef: pr.GetHead().GetRef(),
BaseRef: pr.GetBase().GetRef(),
HeadSHA: pr.GetHead().GetSHA(),
BaseSHA: pr.GetBase().GetSHA(),
State: state,
}, nil
}
// ListReviews returns the reviews on a PR with ID > sinceID.
func (c *GitHubClient) ListReviews(ctx context.Context, owner, repo string, number int, sinceID int64) ([]Review, error) {
var out []Review
opts := &github.ListOptions{PerPage: 100}
for {
reviews, resp, err := c.gh.PullRequests.ListReviews(ctx, owner, repo, number, opts)
if err != nil {
return nil, fmt.Errorf("list reviews %s/%s#%d: %w", owner, repo, number, err)
}
for _, r := range reviews {
if r.GetID() <= sinceID {
continue
}
out = append(out, Review{
ID: r.GetID(),
Author: r.GetUser().GetLogin(),
State: normalizeReviewState(r.GetState()),
Body: r.GetBody(),
SubmittedAt: r.GetSubmittedAt().Time,
})
}
if resp.NextPage == 0 {
break
}
opts.Page = resp.NextPage
}
return out, nil
}
// ListReviewComments returns the review comments on a PR with ID > sinceID.
func (c *GitHubClient) ListReviewComments(ctx context.Context, owner, repo string, number int, sinceID int64) ([]ReviewComment, error) {
var out []ReviewComment
opts := &github.PullRequestListCommentsOptions{PerPage: 100}
for {
comments, resp, err := c.gh.PullRequests.ListComments(ctx, owner, repo, number, opts)
if err != nil {
return nil, fmt.Errorf("list review comments %s/%s#%d: %w", owner, repo, number, err)
}
for _, cm := range comments {
if cm.GetID() <= sinceID {
continue
}
line := cm.GetOriginalLine()
if line == 0 {
line = cm.GetLine()
}
out = append(out, ReviewComment{
ID: cm.GetID(),
ReviewID: cm.GetPullRequestReviewID(),
Author: cm.GetUser().GetLogin(),
Body: cm.GetBody(),
Path: cm.GetPath(),
Line: line,
InReplyTo: cm.GetInReplyTo(),
CreatedAt: cm.GetCreatedAt().Time,
})
}
if resp.NextPage == 0 {
break
}
opts.Page = resp.NextPage
}
return out, nil
}
// ReplyToReview posts a reply to an existing review comment.
func (c *GitHubClient) ReplyToReview(ctx context.Context, owner, repo string, number int, commentID int64, body string) error {
if _, _, err := c.gh.PullRequests.CreateCommentInReplyTo(ctx, owner, repo, number, body, commentID); err != nil {
return fmt.Errorf("reply to review comment %d on %s/%s#%d: %w", commentID, owner, repo, number, err)
}
return nil
}
// CreateReviewComments posts line-anchored review comments, one GitHub call per
// comment, anchored to the RIGHT (new) side of the pull request's head revision.
//
// The head SHA is read here rather than taken from the caller: it is what the
// comments are anchored to, and the caller that produced the line numbers (a
// workflow stage running in archie-agent) holds no forge credentials to read it
// with. reviewedHeadSHA is the revision those line numbers were measured on, and
// the set is refused outright if the head has moved past it -- see
// reviewHeadDrift.
//
// A comment GitHub refuses -- a line that falls outside the diff, a file the
// push renamed -- does not abandon the rest. The failures are joined and
// returned, so one unanchorable finding cannot silently drop the others.
func (c *GitHubClient) CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []InlineReviewComment) error {
head, err := c.reviewHeadSHA(ctx, owner, repo, number)
if err != nil {
return err
}
if err := reviewHeadDrift(owner, repo, number, head, reviewedHeadSHA); err != nil {
return err
}
var errs []error
for _, cm := range comments {
comment := &github.PullRequestComment{
Body: new(cm.Body),
Path: new(cm.Path),
Line: new(cm.Line),
Side: new("RIGHT"),
CommitID: new(head),
}
if _, _, err := c.gh.PullRequests.CreateComment(ctx, owner, repo, number, comment); err != nil {
errs = append(errs, fmt.Errorf("create review comment %s:%d on %s/%s#%d: %w", cm.Path, cm.Line, owner, repo, number, err))
}
}
return errors.Join(errs...)
}
// reviewHeadSHA resolves the commit a PR's line numbers are anchored to. A
// forge that reports an empty head SHA is a failure, not an anchor: an empty
// commit_id makes GitHub reject every comment in the set with nothing that says
// why.
func (c *GitHubClient) reviewHeadSHA(ctx context.Context, owner, repo string, number int) (string, error) {
pr, err := c.GetPullRequest(ctx, owner, repo, number)
if err != nil {
return "", err
}
if pr.HeadSHA == "" {
return "", fmt.Errorf("resolve head revision of %s/%s#%d: the forge reported no head sha", owner, repo, number)
}
return pr.HeadSHA, nil
}
// CloseIssue closes an issue with a final comment (feasibility "won't do").
func (c *GitHubClient) CloseIssue(ctx context.Context, owner, repo string, number int, comment string) error {
if comment != "" {
if _, err := c.Comment(ctx, owner, repo, number, comment); err != nil {
return err
}
}
_, _, err := c.gh.Issues.Edit(ctx, owner, repo, number,
&github.IssueRequest{State: new("closed")})
return err
}
// LinkBranch associates a branch with an issue (GitHub stub -- Gitea is primary).
func (c *GitHubClient) LinkBranch(ctx context.Context, owner, repo string, issueNumber int, branch string) error {
return nil
}
// State labels mirror the task lifecycle onto the forge so archie's
// status is visible at a glance. SQLite remains the source of truth;
// labels are the human-facing projection -- and removing the parked
// label is the forge-native retry trigger.
// Label strings are configured via [dispatch.labels]; these are the
// built-in defaults used as a fallback when config is absent.
// stateLabelColors maps label name → colour for on-demand creation.
var stateLabelColors = map[string]string{
"archie:queued": "bfd4f2", // grey-blue
"archie:working": "1d76db", // blue
"archie:waiting": "fbca04", // yellow
"archie:pr": "0e8a16", // green
"archie:parked": "d93f0b", // orange-red
}
// defaultLabelColor is used for custom labels not in stateLabelColors.
const defaultLabelColor = "bfd4f2"
// React adds an emoji reaction to an issue -- the instant "received"
// acknowledgement on pickup.
func (c *GitHubClient) React(ctx context.Context, owner, repo string, number int, reaction string) error {
_, _, err := c.gh.Reactions.CreateIssueReaction(ctx, owner, repo, number, reaction)
return err
}
// ensureLabel creates the state label in the repo if it doesn't exist.
func (c *GitHubClient) ensureLabel(ctx context.Context, owner, repo, name string) {
key := owner + "/" + repo + "/" + name
c.labelMu.Lock()
seen := c.labelsEnsured[key]
c.labelMu.Unlock()
if seen {
return
}
color := stateLabelColors[name]
if color == "" {
color = defaultLabelColor
}
_, _, err := c.gh.Issues.CreateLabel(ctx, owner, repo, &github.Label{
Name: new(name),
Color: new(color),
Description: new("archie task state (managed automatically)"),
})
// 422 = already exists; both outcomes mean the label is available.
if err != nil && !strings.Contains(err.Error(), "already_exists") {
c.log.Warn("create label failed", "label", name, "err", err)
return
}
c.labelMu.Lock()
if c.labelsEnsured == nil {
c.labelsEnsured = map[string]bool{}
}
c.labelsEnsured[key] = true
c.labelMu.Unlock()
}
// SetStateLabel makes label the issue's only state label, removing any
// other label found in knownLabels first. An empty label clears all
// state labels (terminal states).
func (c *GitHubClient) SetStateLabel(ctx context.Context, owner, repo string, number int, label string, knownLabels []string) {
known := make(map[string]bool, len(knownLabels))
for _, l := range knownLabels {
known[l] = true
}
issue, _, err := c.gh.Issues.Get(ctx, owner, repo, number)
if err != nil {
c.log.Warn("set state label: get issue failed", "issue", number, "err", err)
return
}
for _, l := range issue.Labels {
name := l.GetName()
if name != label && known[name] {
if _, err := c.gh.Issues.RemoveLabelForIssue(ctx, owner, repo, number, name); err != nil {
c.log.Warn("remove state label failed", "label", name, "err", err)
}
}
if name == label {
label = "" // already present; nothing to add
}
}
if label == "" {
return
}
c.ensureLabel(ctx, owner, repo, label)
if _, _, err := c.gh.Issues.AddLabelsToIssue(ctx, owner, repo, number, []string{label}); err != nil {
c.log.Warn("add state label failed", "label", label, "err", err)
}
}
// VerifyPush confirms the token can push to the repo (permission check
// at startup so misconfiguration surfaces before any work is claimed).
func (c *GitHubClient) VerifyPush(ctx context.Context, owner, repo string) error {
r, _, err := c.gh.Repositories.Get(ctx, owner, repo)
if err != nil {
return fmt.Errorf("get repo %s/%s: %w", owner, repo, err)
}
perms := r.GetPermissions()
if !perms["push"] {
return fmt.Errorf("no push permission on %s/%s", owner, repo)
}
return nil
}