gitprovider

package
v0.10.257 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package gitprovider defines the provider-neutral git host seam.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrAuth       = errors.New("gitprovider: authentication failed")
	ErrPermission = errors.New("gitprovider: permission denied")
	// ErrThreadResolutionUnsupported indicates the provider accepted review
	// posting writes, but the active credential cannot resolve review threads.
	ErrThreadResolutionUnsupported = errors.New("gitprovider: thread resolution unsupported for current credential")
	// ErrIneligibleReviewAuthority indicates the credential can talk to the
	// host, but the resolved posting identity is not eligible for GitHub to
	// count APPROVE/REQUEST_CHANGES toward PR state on the target repository.
	ErrIneligibleReviewAuthority = errors.New("gitprovider: posting identity cannot create opinionated reviews for this repository")
	ErrNotFound                  = errors.New("gitprovider: target not found")
	ErrRetryable                 = errors.New("gitprovider: retryable upstream error")
	ErrConflict                  = errors.New("gitprovider: already exists")
	ErrStaleSHA                  = errors.New("gitprovider: pinned SHA is no longer current")
	// ErrDiffTooLarge indicates the host declined to return a diff because it
	// exceeds the host API's size limit. GitHub, for example, responds with
	// HTTP 406 for pull request diffs beyond its line cap instead of returning
	// a truncated diff.
	ErrDiffTooLarge = errors.New("gitprovider: diff too large for host API")
)

Typed provider errors. Concrete adapters map host-specific failures into these sentinels so callers can classify outcomes without knowing wire details.

Functions

func WrapError 

func WrapError(kind error, op Operation, err error) error

WrapError wraps err with a typed provider error kind and operation.

Types

type CommentID 

type CommentID string

CommentID identifies a provider comment.

type Credential 

type Credential struct {
	Type        string
	Token       string
	Login       string
	ID          string
	DisplayName string
}

Credential carries already-resolved credential material. This package never reads config, keyrings, environment variables, or files.

type Fake 

type Fake struct {
	// contains filtered or unexported fields
}

Fake is an importable, concurrency-safe GitProvider test double.

func (*Fake) Capabilities 

func (f *Fake) Capabilities() ProviderCaps

Capabilities returns the configured fake provider capabilities.

func (*Fake) GetDiff 

func (f *Fake) GetDiff(_ context.Context, ref PRRef) (UnifiedDiff, error)

GetDiff returns the canned unified diff for ref.

func (*Fake) GetFileAtRef 

func (f *Fake) GetFileAtRef(_ context.Context, ref PRRef, gitRef string, path string) ([]byte, error)

GetFileAtRef returns the canned file contents for the full ref/path selector.

func (*Fake) GetPR 

func (f *Fake) GetPR(_ context.Context, ref PRRef) (PR, error)

GetPR returns the canned PR snapshot for ref.

func (*Fake) ListInlineThreads 

func (f *Fake) ListInlineThreads(_ context.Context, ref PRRef) ([]InlineThread, error)

ListInlineThreads returns the canned inline threads for ref.

func (*Fake) ListIssueComments 

func (f *Fake) ListIssueComments(_ context.Context, ref PRRef) ([]IssueComment, error)

ListIssueComments returns the canned issue comments for ref.

func (*Fake) ListReviews 

func (f *Fake) ListReviews(_ context.Context, ref PRRef) ([]Review, error)

ListReviews returns the canned reviews for ref.

func (*Fake) ListTreeAtRef 

func (f *Fake) ListTreeAtRef(_ context.Context, ref PRRef, gitRef string, path string) ([]TreeEntry, error)

ListTreeAtRef returns the canned tree entries for the full ref/path selector.

func (*Fake) PostInlineComment 

func (f *Fake) PostInlineComment(_ context.Context, ref PRRef, c InlineComment) (CommentID, error)

PostInlineComment validates and records an inline comment write.

func (*Fake) PostIssueComment 

func (f *Fake) PostIssueComment(_ context.Context, ref PRRef, body string) (CommentID, error)

PostIssueComment validates and records an issue comment write.

func (*Fake) RecordedInlineComments 

func (f *Fake) RecordedInlineComments(ref PRRef) []InlineComment

RecordedInlineComments returns successful inline-comment writes for ref.

func (*Fake) RecordedIssueComments 

func (f *Fake) RecordedIssueComments(ref PRRef) []string

RecordedIssueComments returns successful issue-comment writes for ref.

func (*Fake) RecordedResolvedThreads 

func (f *Fake) RecordedResolvedThreads(ref PRRef) []ThreadID

RecordedResolvedThreads returns successful thread resolutions for ref.

func (*Fake) RecordedReviews 

func (f *Fake) RecordedReviews(ref PRRef) []ReviewRequest

RecordedReviews returns successful review submissions for ref.

func (*Fake) RecordedThreadReplies 

func (f *Fake) RecordedThreadReplies(ref PRRef) []ThreadReply

RecordedThreadReplies returns successful thread replies for ref.

func (*Fake) ReplyToThread 

func (f *Fake) ReplyToThread(_ context.Context, ref PRRef, threadID ThreadID, body string) (CommentID, error)

ReplyToThread validates and records a thread reply write.

func (*Fake) ResolveThread 

func (f *Fake) ResolveThread(_ context.Context, ref PRRef, threadID ThreadID) error

ResolveThread validates and records a thread resolution write.

func (*Fake) ReviewAuthority added in v0.9.190 

func (f *Fake) ReviewAuthority(_ context.Context, ref PRRef, identity Identity) (ReviewAuthority, error)

ReviewAuthority returns the configured authority for ref/login.

func (*Fake) SetCallHook added in v0.10.238 

func (f *Fake) SetCallHook(hook func(Operation))

SetCallHook configures a function called before each GitProvider operation. Passing nil clears the hook.

func (*Fake) SetCapabilities 

func (f *Fake) SetCapabilities(caps ProviderCaps)

SetCapabilities configures the capabilities returned by Capabilities.

func (*Fake) SetDiff 

func (f *Fake) SetDiff(ref PRRef, diff UnifiedDiff) error

SetDiff configures the unified diff for ref.

func (*Fake) SetError 

func (f *Fake) SetError(op Operation, err error)

SetError injects err for op. Passing nil clears the injected error.

func (*Fake) SetFileAtRef 

func (f *Fake) SetFileAtRef(ref PRRef, gitRef, path string, contents []byte) error

SetFileAtRef configures file contents for a full ref/path selector.

func (*Fake) SetIdentity 

func (f *Fake) SetIdentity(identity Identity)

SetIdentity configures the identity returned by WhoAmI.

func (*Fake) SetInlineThreads 

func (f *Fake) SetInlineThreads(ref PRRef, threads []InlineThread) error

SetInlineThreads configures inline threads for ref.

func (*Fake) SetIssueComments 

func (f *Fake) SetIssueComments(ref PRRef, comments []IssueComment) error

SetIssueComments configures issue comments for ref.

func (*Fake) SetPR 

func (f *Fake) SetPR(ref PRRef, pr PR) error

SetPR configures the PR snapshot for ref.

func (*Fake) SetReviewAuthority added in v0.9.190 

func (f *Fake) SetReviewAuthority(ref PRRef, login string, authority ReviewAuthority) error

SetReviewAuthority configures the authority lookup for ref/login.

func (*Fake) SetReviews 

func (f *Fake) SetReviews(ref PRRef, reviews []Review) error

SetReviews configures reviews for ref.

func (*Fake) SetTreeAtRef 

func (f *Fake) SetTreeAtRef(ref PRRef, gitRef, path string, entries []TreeEntry) error

SetTreeAtRef configures tree entries for a full ref/path selector.

func (*Fake) SubmitReview 

func (f *Fake) SubmitReview(_ context.Context, ref PRRef, r ReviewRequest) (ReviewID, error)

SubmitReview validates and records a review submission write.

func (*Fake) WhoAmI 

func (f *Fake) WhoAmI(_ context.Context, _ Credential) (Identity, error)

WhoAmI returns the configured fake identity or an injected error.

type GitProvider 

type GitProvider interface {
	WhoAmI(ctx context.Context, creds Credential) (Identity, error)
	ReviewAuthority(ctx context.Context, ref PRRef, identity Identity) (ReviewAuthority, error)

	GetPR(ctx context.Context, ref PRRef) (PR, error)
	GetDiff(ctx context.Context, ref PRRef) (UnifiedDiff, error)
	GetFileAtRef(ctx context.Context, ref PRRef, gitRef string, path string) ([]byte, error)
	ListTreeAtRef(ctx context.Context, ref PRRef, gitRef string, path string) ([]TreeEntry, error)
	ListInlineThreads(ctx context.Context, ref PRRef) ([]InlineThread, error)
	ListReviews(ctx context.Context, ref PRRef) ([]Review, error)
	ListIssueComments(ctx context.Context, ref PRRef) ([]IssueComment, error)

	PostInlineComment(ctx context.Context, ref PRRef, c InlineComment) (CommentID, error)
	ReplyToThread(ctx context.Context, ref PRRef, threadID ThreadID, body string) (CommentID, error)
	ResolveThread(ctx context.Context, ref PRRef, threadID ThreadID) error
	PostIssueComment(ctx context.Context, ref PRRef, body string) (CommentID, error)
	SubmitReview(ctx context.Context, ref PRRef, r ReviewRequest) (ReviewID, error)

	Capabilities() ProviderCaps
}

GitProvider is the host-agnostic seam for pull-request reads and writes.

type Identity 

type Identity struct {
	Login       string
	ID          string
	DisplayName string
}

Identity describes a git-host user without binding callers to one host's account schema.

func (Identity) Same added in v0.10.228 

func (i Identity) Same(other Identity) bool

Same reports whether two identities have the same non-empty ID, falling back to an exact, case-sensitive login match.

type InlineComment 

type InlineComment struct {
	CommitSHA    string
	Body         string
	Path         string
	Side         review.DiffSide
	Line         int
	SubjectType  review.AnchorKind
	DiffPosition int
}

InlineComment is the write request for posting an inline comment.

func (InlineComment) Validate 

func (c InlineComment) Validate() error

Validate checks provider-seam invariants for an inline comment write.

type InlineThread 

type InlineThread struct {
	ID          ThreadID
	Resolved    bool
	Path        string
	Side        review.DiffSide
	Line        int
	SubjectType review.AnchorKind
	CommitSHA   string
	Comments    []ThreadComment
}

InlineThread is a provider-neutral inline review thread.

type IssueComment 

type IssueComment struct {
	ID        CommentID
	Body      string
	Author    Identity
	URL       string
	CreatedAt time.Time
	UpdatedAt time.Time
}

IssueComment is a provider-neutral issue or pull-request comment.

type Operation 

type Operation string

Operation identifies a GitProvider method for fake error injection and provider-error metadata. 

const (
	OperationWhoAmI             Operation = "WhoAmI"
	OperationReviewAuthority    Operation = "ReviewAuthority"
	OperationGetPR              Operation = "GetPR"
	OperationGetDiff            Operation = "GetDiff"
	OperationGetDiffBetweenRefs Operation = "GetDiffBetweenRefs"
	OperationGetFileAtRef       Operation = "GetFileAtRef"
	OperationListTreeAtRef      Operation = "ListTreeAtRef"
	OperationListInlineThreads  Operation = "ListInlineThreads"
	OperationListReviews        Operation = "ListReviews"
	OperationListIssueComments  Operation = "ListIssueComments"
	OperationPostInlineComment  Operation = "PostInlineComment"
	OperationReplyToThread      Operation = "ReplyToThread"
	OperationResolveThread      Operation = "ResolveThread"
	OperationPostIssueComment   Operation = "PostIssueComment"
	OperationSubmitReview       Operation = "SubmitReview"
)

GitProvider operation names.

type PR 

type PR struct {
	Ref    PRRef
	Title  string
	Body   string
	URL    string
	State  PRState
	Author Identity
	Head   PRBranchRef
	Base   PRBranchRef
}

PR is the provider-neutral pull request snapshot used by later pipeline stages.

type PRBranchRef 

type PRBranchRef struct {
	Host  string
	Owner string
	Repo  string
	Name  string
	Ref   string
	SHA   string
}

PRBranchRef identifies a base or head ref. Host/Owner/Repo are explicit because a pull request head may live in a fork.

type PRRef 

type PRRef struct {
	Host   string
	Owner  string
	Repo   string
	Number int
}

PRRef identifies one pull request on one host.

func (PRRef) Validate 

func (r PRRef) Validate() error

Validate checks that r can be used as a stable provider and ledger key.

type PRState 

type PRState string

PRState is a normalized provider-neutral pull request state. 

const (
	PRStateOpen   PRState = "open"
	PRStateClosed PRState = "closed"
	PRStateMerged PRState = "merged"
)

Pull request states.

func (PRState) Valid 

func (s PRState) Valid() bool

Valid reports whether s is one of the known pull request states.

type ProviderCaps 

type ProviderCaps struct {
	NativeFileLevelComments bool
	ThreadResolution        bool
	BundleInlineOnSubmit    bool
}

ProviderCaps advertises host features that affect posting choices.

type ProviderError 

type ProviderError struct {
	Op   Operation
	Kind error
	Err  error
}

ProviderError annotates a typed provider failure with the operation that produced it and, when available, a more specific wrapped cause.

func (*ProviderError) Error 

func (e *ProviderError) Error() string

func (*ProviderError) Is 

func (e *ProviderError) Is(target error) bool

Is makes Kind errors.Is-matchable. Unwrap exposes Err to the standard chain.

func (*ProviderError) Unwrap 

func (e *ProviderError) Unwrap() error

type Review 

type Review struct {
	ID          ReviewID
	Body        string
	Author      Identity
	State       ReviewState
	Event       review.ReviewEvent
	CommitSHA   string
	URL         string
	SubmittedAt time.Time
}

Review is a provider-neutral pull-request review record.

type ReviewAuthority added in v0.9.190 

type ReviewAuthority struct {
	Eligible   bool
	Permission string
	RoleName   string
}

ReviewAuthority describes whether the resolved posting identity can create a GitHub review that counts as APPROVE/REQUEST_CHANGES for a specific repo.

type ReviewID 

type ReviewID string

ReviewID identifies a provider pull-request review.

type ReviewRequest 

type ReviewRequest struct {
	CommitSHA string
	Event     review.ReviewEvent
	Body      string
	Comments  []InlineComment
}

ReviewRequest is the write request for submitting a pull request review.

func (ReviewRequest) Validate 

func (r ReviewRequest) Validate() error

Validate checks provider-seam invariants for a review submission.

type ReviewState 

type ReviewState string

ReviewState is a normalized provider-neutral pull request review state. 

const (
	ReviewStateApproved         ReviewState = "approved"
	ReviewStateChangesRequested ReviewState = "changes_requested"
	ReviewStateCommented        ReviewState = "commented"
	ReviewStateDismissed        ReviewState = "dismissed"
	ReviewStatePending          ReviewState = "pending"
)

Pull request review states.

func (ReviewState) Valid 

func (s ReviewState) Valid() bool

Valid reports whether s is one of the known review states.

type ThreadComment 

type ThreadComment struct {
	ID          CommentID
	ThreadID    ThreadID
	Body        string
	Author      Identity
	CommitSHA   string
	Path        string
	Side        review.DiffSide
	Line        int
	SubjectType review.AnchorKind
	URL         string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

ThreadComment is one host comment inside an inline thread.

type ThreadID 

type ThreadID string

ThreadID identifies a provider inline review thread.

type ThreadReply 

type ThreadReply struct {
	ThreadID ThreadID
	Body     string
}

ThreadReply records one ReplyToThread write.

type TreeEntry 

type TreeEntry struct {
	Path string
	Type string
	SHA  string
}

TreeEntry is one git tree entry at a ref.

type UnifiedDiff 

type UnifiedDiff struct {
	Raw string
}

UnifiedDiff is a provider-neutral unified diff payload.

Source Files

View all Source files

Directories

Path Synopsis
Package github adapts GitHub REST and GraphQL APIs to gitprovider read models.
 Package github adapts GitHub REST and GraphQL APIs to gitprovider read models.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.