The issue poller published title and body of every labelled or assigned issue to the agent. It now keeps only write-access authors, failing closed when the forge cannot answer. The filter moves to forge.WriterIssues, shared with the issue_list tool.
262 lines
9.6 KiB
Go
262 lines
9.6 KiB
Go
// 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)
|
|
}
|