github

package
v0.8.3 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package github wraps the GitHub CLI operations live-pr needs.

Index

Constants

View Source 
const CacheVersion = 1
View Source 
const PRPageSize = 25

Variables

View Source 
var ErrPRNotFound = errors.New("pull request not found")

ErrPRNotFound means no open pull request exists for the requested head.

Functions

func SaveCache 

func SaveCache(path string, c Cache) error

SaveCache atomically replaces path with c.

func SaveNavigatorCache 

func SaveNavigatorCache(path string, c NavigatorCache) error

func SaveReviewDraft added in v0.2.0 

func SaveReviewDraft(path string, draft ReviewDraft) error

func StatusHint added in v0.6.8 

func StatusHint(err error) string

StatusHint classifies a fetch failure for the status line so the TUI can tell setup problems apart from being offline. It returns "" when the failure looks like plain network trouble — callers keep their existing offline wording — and a short actionable hint otherwise. Deliberately a dumb string check over the flat error text runError/commandError build.

func ValidateReviewComment added in v0.2.0 

func ValidateReviewComment(comment ReviewComment) error

func ValidateReviewDraft added in v0.2.0 

func ValidateReviewDraft(draft ReviewDraft) error

func ValidateReviewEvent added in v0.2.0 

func ValidateReviewEvent(event ReviewEvent) error

Types

type Activity 

type Activity struct {
	ID        int64  `json:"id"`
	NodeID    string `json:"node_id"`
	Event     string `json:"event"`
	CreatedAt string `json:"created_at"`
	CommitID  string `json:"commit_id"`
	Actor     struct {
		Login     string `json:"login"`
		AvatarURL string `json:"avatar_url,omitempty"`
	} `json:"actor"`
	Label struct {
		Name string `json:"name"`
	} `json:"label"`
	Assignee struct {
		Login string `json:"login"`
	} `json:"assignee"`
	RequestedReviewer struct {
		Login string `json:"login"`
	} `json:"requested_reviewer"`
	Rename struct {
		From string `json:"from"`
		To   string `json:"to"`
	} `json:"rename"`
}

Activity is a non-comment PR timeline event from GitHub's issue events API.

type Cache 

type Cache struct {
	Version                      int                   `json:"version"`
	Head                         string                `json:"head,omitempty"`
	PR                           *PR                   `json:"pr,omitempty"`
	ExplicitCheckout             bool                  `json:"explicit_checkout,omitempty"`
	Comments                     []Comment             `json:"comments,omitempty"`
	Activities                   []Activity            `json:"activities,omitempty"`
	Reviews                      []Review              `json:"reviews,omitempty"`
	ReviewComments               []ReviewThreadComment `json:"review_comments,omitempty"`
	FetchedAt                    string                `json:"fetched_at,omitempty"`
	LastPublishedManagedBodyHash string                `json:"last_published_managed_body_hash,omitempty"`
}

Cache is branch-local mutable GitHub state. Remote resources intentionally stay separate from the append-only local timeline.

func LoadCache 

func LoadCache(path, head string) (Cache, error)

LoadCache loads path. A missing file is an empty cache, while malformed or unsupported data is reported so callers can keep running without trusting it.

func NewCache 

func NewCache(head string) Cache

NewCache returns an initialized empty cache.

func (Cache) Base 

func (c Cache) Base(fallback string) string

Base returns the bound PR base when known, otherwise fallback.

type Client 

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

Client runs GitHub operations through gh.

func New 

func New() Client

New returns a GitHub CLI client.

func (Client) Checkout 

func (c Client) Checkout(number int) error

Checkout checks out a pull request using GitHub CLI's native branch handling.

func (Client) Close 

func (c Client) Close(number int) error

Close closes a pull request without merging it.

func (Client) Create 

func (c Client) Create(base, head, title, bodyFile string, draft bool) (string, error)

Create creates a PR and returns gh's output (normally its URL).

func (Client) DeleteIssueComment added in v0.5.1 

func (c Client) DeleteIssueComment(id int64) error

DeleteIssueComment removes a conversation comment by its ID.

func (Client) EditIssueComment added in v0.5.0 

func (c Client) EditIssueComment(id int64, body string) error

EditIssueComment updates an existing conversation comment by its ID.

func (Client) Find 

func (c Client) Find(number int) (PR, error)

func (Client) FindAllForHead added in v0.5.0 

func (c Client) FindAllForHead(head string) ([]PR, error)

FindAllForHead returns every PR (any state) whose head is the given branch.

func (Client) FindChecks added in v0.2.0 

func (c Client) FindChecks(number int) (PR, error)

FindChecks loads only the current head revision and its CI rollup. FindChecks polls the CI state. It also carries the pull request state: this call outlives a merge, and the poller needs to know when to stop.

func (Client) FindForHead 

func (c Client) FindForHead(head string) (PR, error)

FindForHead prefers an open PR, then returns the newest PR in any state. When multiple PRs share the same head branch, the newest (highest number) wins.

func (Client) FindOpen 

func (c Client) FindOpen(head string) (PR, error)

FindOpen finds the open PR for head. Operational errors are returned as-is; only a successful empty list becomes ErrPRNotFound.

func (Client) FindPreview 

func (c Client) FindPreview(number int) (PR, error)

FindPreview loads the expensive preview fields for one PR only.

func (Client) IssueActivities 

func (c Client) IssueActivities(number int) ([]Activity, error)

IssueActivities returns non-comment activity from the PR timeline.

func (Client) IssueComments 

func (c Client) IssueComments(number int) ([]Comment, error)

IssueComments returns every top-level Conversation comment for a PR.

func (Client) LoadPRDetail 

func (c Client) LoadPRDetail(number int, prev PRDetail) PRDetail

LoadPRDetail loads preview metadata, comments, and activity concurrently. prev is the caller's cached snapshot of the same PR: when it carries comments, only those created or updated since the newest cached updated_at are fetched and merged in by ID. An empty prev, a number mismatch, or any doubt about the cache loads everything, exactly like a first load.

func (Client) Merge 

func (c Client) Merge(number int, headOID string, method MergeMethod) error

Merge merges a pull request with the given method.

func (Client) PostIssueComment added in v0.5.0 

func (c Client) PostIssueComment(number int, body string) error

PostIssueComment posts a conversation comment on a pull request.

func (Client) ReviewComments added in v0.5.0 

func (c Client) ReviewComments(number int) ([]ReviewThreadComment, error)

ReviewComments returns the inline review comments for a pull request.

func (Client) Reviews added in v0.5.0 

func (c Client) Reviews(number int) ([]Review, error)

Reviews returns the submitted reviews for a pull request.

func (Client) SearchPRs 

func (c Client) SearchPRs(query, cursor string) (PRPage, error)

SearchPRs returns exactly one page. Callers decide when to request PageInfo.EndCursor.

func (Client) SetStatus added in v0.2.1 

func (c Client) SetStatus(pr PR, target string) error

SetStatus changes a pull request to open, closed, or draft.

func (Client) SubmitReview added in v0.2.0 

func (c Client) SubmitReview(draft ReviewDraft, event ReviewEvent) error

SubmitReview publishes a complete review and its inline comments atomically.

func (Client) Update 

func (c Client) Update(number int, title, bodyFile string) error

Update replaces the title and body of an existing PR. It addresses the PR by number: several PRs may share one head branch, and a branch-name edit could land on the wrong one.

func (Client) UpdateBody added in v0.5.0 

func (c Client) UpdateBody(number int, bodyFile string) error

UpdateBody replaces only the body of an existing PR, preserving the title.

type Comment 

type Comment struct {
	ID        int64  `json:"id"`
	NodeID    string `json:"node_id"`
	Body      string `json:"body"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
	HTMLURL   string `json:"html_url"`
	User      struct {
		Login     string `json:"login"`
		AvatarURL string `json:"avatar_url,omitempty"`
	} `json:"user"`
}

Comment is a top-level PR conversation comment.

type IssueRef added in v0.7.0 

type IssueRef struct {
	Number int    `json:"number"`
	Title  string `json:"title"`
}

IssueRef is a linked issue a pull request closes on merge.

type MergeMethod added in v0.6.8 

type MergeMethod string

MergeMethod selects how gh lands a pull request. 

const (
	MergeCommit MergeMethod = "merge"
	MergeSquash MergeMethod = "squash"
	MergeRebase MergeMethod = "rebase"
)
type NavigatorCache struct {
	Version       int                    `json:"version"`
	Repository    string                 `json:"repository,omitempty"`
	ViewerLogin   string                 `json:"viewer_login,omitempty"`
	PRs           []PR                   `json:"prs,omitempty"`
	PRsState      string                 `json:"prs_state,omitempty"`
	FetchedStates map[string]bool        `json:"fetched_states,omitempty"`
	Views         map[string]PRViewCache `json:"views,omitempty"`
	Snapshots     map[string]PRSnapshot  `json:"snapshots,omitempty"`
	FetchedAt     string                 `json:"fetched_at,omitempty"`
}

NavigatorCache is repository-wide browse state. Publish conflict state remains in the branch-local Cache and is intentionally absent here.

func LoadNavigatorCache 

func LoadNavigatorCache(path string) (NavigatorCache, error)

func NewNavigatorCache 

func NewNavigatorCache() NavigatorCache
func (c NavigatorCache) Clone() NavigatorCache

Clone returns a copy that is safe to marshal while the original keeps mutating: the PRs backing array is rewritten in place by preview updates and the maps by SetView/SetSnapshot, but their values are only ever replaced wholesale, so element copies suffice. 

func (c *NavigatorCache) PrunePRs()
func (c *NavigatorCache) SetSnapshot(snapshot PRSnapshot)
func (c *NavigatorCache) SetView(name string, prs []PR, total int, fetchedAt string)
func (c NavigatorCache) Snapshot(number int) (PRSnapshot, bool)
func (c NavigatorCache) View(name string) ([]PR, PRViewCache, bool)

type PR 

type PR struct {
	Number                int                     `json:"number"`
	URL                   string                  `json:"url"`
	Title                 string                  `json:"title"`
	Body                  string                  `json:"body"`
	State                 string                  `json:"state"`
	BaseRefName           string                  `json:"baseRefName,omitempty"`
	BaseRefOID            string                  `json:"baseRefOid,omitempty"`
	HeadRefName           string                  `json:"headRefName,omitempty"`
	HeadRefOID            string                  `json:"headRefOid,omitempty"`
	IsDraft               bool                    `json:"isDraft,omitempty"`
	IsCrossRepository     bool                    `json:"isCrossRepository,omitempty"`
	Mergeable             string                  `json:"mergeable,omitempty"`
	MergeStateStatus      string                  `json:"mergeStateStatus,omitempty"`
	ReviewDecision        string                  `json:"reviewDecision,omitempty"`
	Additions             int                     `json:"additions,omitempty"`
	Deletions             int                     `json:"deletions,omitempty"`
	ChangedFiles          int                     `json:"changedFiles,omitempty"`
	UpdatedAt             string                  `json:"updatedAt,omitempty"`
	Conversation          []PRConversationComment `json:"comments,omitempty"`
	CommentCount          int                     `json:"commentCount,omitempty"`
	CommitCount           int                     `json:"commitCount,omitempty"`
	Commits               []PRCommit              `json:"commits,omitempty"`
	Checks                []PRCheck               `json:"statusCheckRollup,omitempty"`
	CheckRollupState      string                  `json:"checkRollupState,omitempty"`
	Author                PRUser                  `json:"author,omitempty"`
	CreatedAt             string                  `json:"createdAt,omitempty"`
	Assignees             []PRUser                `json:"assignees,omitempty"`
	Labels                []PRLabel               `json:"labels,omitempty"`
	ReviewRequests        []PRUser                `json:"reviewRequests,omitempty"`
	ClosingIssues         []IssueRef              `json:"closingIssues,omitempty"`
	ViewerReviewRequested bool                    `json:"viewerReviewRequested,omitempty"`
	PreviewLoaded         bool                    `json:"previewLoaded,omitempty"`
}

PR is the remote pull-request state needed by live-pr.

type PRCheck 

type PRCheck struct {
	Name         string `json:"name,omitempty"`
	Context      string `json:"context,omitempty"`
	Status       string `json:"status,omitempty"`
	Conclusion   string `json:"conclusion,omitempty"`
	State        string `json:"state,omitempty"`
	WorkflowName string `json:"workflowName,omitempty"`
	StartedAt    string `json:"startedAt,omitempty"`
	CompletedAt  string `json:"completedAt,omitempty"`
	DetailsURL   string `json:"detailsUrl,omitempty"`
	TargetURL    string `json:"targetUrl,omitempty"`
}

PRCheck covers both GitHub check runs and legacy status contexts.

func (PRCheck) URL added in v0.6.8 

func (c PRCheck) URL() string

URL is the check's log page: a check run's detailsUrl, or a legacy status context's targetUrl.

type PRCommit 

type PRCommit struct {
	OID              string `json:"oid"`
	CommittedDate    string `json:"committedDate,omitempty"`
	MessageHeadline  string `json:"messageHeadline,omitempty"`
	CheckRollupState string `json:"checkRollupState,omitempty"`
}

PRCommit is one pull-request commit with its commit-specific CI rollup.

type PRConversationComment 

type PRConversationComment struct {
	Author    PRUser `json:"author"`
	Body      string `json:"body"`
	CreatedAt string `json:"createdAt"`
	URL       string `json:"url,omitempty"`
}

PRConversationComment is compact list-preview conversation metadata.

type PRDetail 

type PRDetail struct {
	PR                PR
	Comments          []Comment
	Activities        []Activity
	Reviews           []Review
	ReviewComments    []ReviewThreadComment
	PreviewErr        error
	CommentsErr       error
	ActivitiesErr     error
	ReviewsErr        error
	ReviewCommentsErr error
}

PRDetail is one concurrently loaded pull-request detail snapshot.

type PRLabel 

type PRLabel struct {
	Name  string `json:"name"`
	Color string `json:"color"`
}

PRLabel is a GitHub label and its six-digit RGB color.

type PRPage 

type PRPage struct {
	Repository  string
	ViewerLogin string
	PRs         []PR
	TotalCount  int
	PageInfo    PageInfo
}

PRPage is one explicitly requested page of lightweight pull-request rows.

type PRSnapshot 

type PRSnapshot struct {
	PR         PR         `json:"pr"`
	Comments   []Comment  `json:"comments,omitempty"`
	Activities []Activity `json:"activities,omitempty"`
	FetchedAt  string     `json:"fetched_at,omitempty"`
}

PRSnapshot is cached Conversation data for one browsed pull request.

type PRUser 

type PRUser struct {
	Login     string `json:"login"`
	AvatarURL string `json:"avatarUrl,omitempty"`
}

PRUser is a GitHub account attached to PR metadata.

type PRViewCache 

type PRViewCache struct {
	Numbers    []int  `json:"numbers,omitempty"`
	TotalCount int    `json:"total_count,omitempty"`
	FetchedAt  string `json:"fetched_at,omitempty"`
}

PRViewCache preserves loaded row order and an exact server count without duplicating PR metadata already stored in NavigatorCache.PRs.

type PageInfo 

type PageInfo struct {
	HasNextPage bool   `json:"hasNextPage"`
	StartCursor string `json:"startCursor"`
	EndCursor   string `json:"endCursor"`
}

PageInfo is one GitHub cursor boundary.

type Review added in v0.5.0 

type Review struct {
	ID          int64  `json:"id"`
	Body        string `json:"body"`
	State       string `json:"state"`
	SubmittedAt string `json:"submitted_at"`
	User        struct {
		Login     string `json:"login"`
		AvatarURL string `json:"avatar_url,omitempty"`
	} `json:"user"`
}

Review is a submitted pull-request review (approve / request-changes / comment) with its optional summary body.

type ReviewComment added in v0.2.0 

type ReviewComment struct {
	Path string `json:"path"`
	Line int    `json:"line"`
	Side string `json:"side"`
	Body string `json:"body"`
}

ReviewComment is one pending inline GitHub review comment.

type ReviewDraft added in v0.2.0 

type ReviewDraft struct {
	Version  int             `json:"version"`
	PR       int             `json:"pr"`
	Commit   string          `json:"commit_id"`
	Body     string          `json:"body,omitempty"`
	Comments []ReviewComment `json:"comments,omitempty"`
}

ReviewDraft is a local, unpublished GitHub pull-request review.

func LoadReviewDraft added in v0.2.0 

func LoadReviewDraft(path string, pr int, commit string) (ReviewDraft, error)

func NewReviewDraft added in v0.2.0 

func NewReviewDraft(pr int, commit string) ReviewDraft

type ReviewEvent added in v0.2.0 

type ReviewEvent string

ReviewEvent is one GitHub review verdict. 

const (
	ReviewCommentEvent        ReviewEvent = "COMMENT"
	ReviewApproveEvent        ReviewEvent = "APPROVE"
	ReviewRequestChangesEvent ReviewEvent = "REQUEST_CHANGES"
)

type ReviewThreadComment added in v0.5.0 

type ReviewThreadComment struct {
	ID        int64  `json:"id"`
	Body      string `json:"body"`
	Path      string `json:"path"`
	Line      int    `json:"line"`
	CreatedAt string `json:"created_at"`
	User      struct {
		Login     string `json:"login"`
		AvatarURL string `json:"avatar_url,omitempty"`
	} `json:"user"`
}

ReviewThreadComment is one inline review comment on a diff line.

Source Files

View all Source files

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.