github

package
v0.3.25 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package github provides GitHub integration for querying PR status.

Package github provides GitHub integration.

Index

Constants

View Source 
const DefaultHost = "github.com"

DefaultHost is the host assumed for shorthand refs ("owner/repo").

Variables

This section is empty.

Functions

func CloneErrorMessage added in v0.3.25 

func CloneErrorMessage(stderr string) string

CloneErrorMessage distills git's stderr to the lines worth showing: progress chatter and the "Cloning into…" banner are dropped, the rest is kept verbatim.

func DefaultCloneRoot added in v0.3.25 

func DefaultCloneRoot() string

DefaultCloneRoot is where clones land unless told otherwise: ~/Projects.

func FetchAllPRsForRepo 

func FetchAllPRsForRepo(repoDir string) map[string]*PRInfo

FetchAllPRsForRepo fetches all open PRs for a repo in a single API call. Returns a map of branch name -> PRInfo. This is much more efficient than fetching per-branch.

Only OPEN PRs are listed. Merged/closed transitions are not discoverable here (a merged PR is simply absent); callers detect those via NeedsReconcile and a targeted GetPRForBranch lookup. An earlier version fetched the 5 most recently merged PRs to catch merges, but that window is far too small for busy repos (dozens of merges between ticks) and gh sorts that list by PR number, not merge time — so most merges were silently missed.

func IsNewerVersion 

func IsNewerVersion(current, latest string) bool

IsNewerVersion returns true if latest is a newer version than current. Both should be semver strings, optionally prefixed with "v".

func LooksLikeRepoRef added in v0.3.25 

func LooksLikeRepoRef(input string) bool

LooksLikeRepoRef reports whether input is shaped like a repo URL at all — used to decide whether a parse failure is worth an inline error (a paste gone wrong) or just an ordinary search term.

func MarshalPRInfo 

func MarshalPRInfo(info *PRInfo) string

MarshalPRInfo converts a PRInfo to JSON string for database storage.

func NeedsReconcile added in v0.3.10 

func NeedsReconcile(openPRs map[string]*PRInfo, branchName string, prNumber int) bool

NeedsReconcile reports whether a task's PR state must be reconciled with a targeted per-branch lookup.

FetchAllPRsForRepo only lists OPEN PRs, so a branch that is absent from that batch but for which we already know a PR number has necessarily left the open set — it merged or closed. The batch can't see that transition, so the caller must fetch the branch individually to learn its terminal state. Without this, merged/closed PRs stay frozen at their last-seen OPEN state on the board.

Types

type AccountType added in v0.2.40 

type AccountType string

AccountType classifies the identity that `gh` is authenticated as. 

const (
	// AccountTypeUnknown means we could not determine the identity.
	AccountTypeUnknown AccountType = "unknown"
	// AccountTypePersonal is a regular GitHub user account (e.g. via `gh auth login`).
	// Personal accounts share a single 5,000 pt/hr GraphQL bucket PER-USER across
	// every machine authenticated as that user — the root cause of bucket exhaustion.
	AccountTypePersonal AccountType = "personal"
	// AccountTypeApp is a GitHub App / bot identity (login ends in "[bot]",
	// API type "Bot"). Each App installation token gets its OWN GraphQL bucket,
	// so it does not contend with other servers.
	AccountTypeApp AccountType = "app"
)

type AuthStatus added in v0.2.40 

type AuthStatus struct {
	GHInstalled bool
	LoggedIn    bool
	TokenValid  bool // false when the token is expired/revoked (401 Bad credentials)

	Account     string
	AccountType AccountType

	// GraphQL rate-limit headroom. Remaining/Limit are -1 when unknown.
	GraphQLRemaining int
	GraphQLLimit     int
	GraphQLResetAt   time.Time

	// Err holds an unexpected error encountered while probing (not auth state).
	Err error
}

AuthStatus is the result of inspecting the local `gh` authentication.

func CheckAuth added in v0.2.40 

func CheckAuth(ctx context.Context) AuthStatus

CheckAuth inspects the local `gh` CLI authentication and rate-limit headroom. It never returns an error for ordinary auth states (not installed, logged out, expired token); those are reported via the returned AuthStatus fields.

func (AuthStatus) Findings added in v0.2.40 

func (s AuthStatus) Findings() []Finding

Findings translates the auth status into ordered diagnostic findings. The most severe issues come first. This is the data `ty doctor` renders.

func (AuthStatus) HasProblems added in v0.2.40 

func (s AuthStatus) HasProblems() bool

HasProblems reports whether any finding is a warning or error.

type CheckState 

type CheckState string

CheckState represents the state of CI checks. 

const (
	CheckStatePending CheckState = "PENDING"
	CheckStatePassing CheckState = "SUCCESS"
	CheckStateFailing CheckState = "FAILURE"
	CheckStateNone    CheckState = ""
)

type CloneDestination added in v0.3.25 

type CloneDestination struct {
	Path string
	// Reuse is true when Path already holds a checkout of the same repo, so
	// there's nothing to clone — the caller can adopt it as-is.
	Reuse bool
	// Renamed is true when the natural directory name was taken by something
	// else and a non-colliding one was picked instead.
	Renamed bool
}

CloneDestination is where a clone will land, and how we got there.

type CloneError added in v0.3.25 

type CloneError struct {
	Stderr string
	Err    error
}

CloneError carries git's own stderr so the UI can show the user exactly what git said (bad auth, no such repo, no network).

func (*CloneError) Error added in v0.3.25 

func (e *CloneError) Error() string

func (*CloneError) Unwrap added in v0.3.25 

func (e *CloneError) Unwrap() error

type Cloner added in v0.3.25 

type Cloner struct {
	// Root is where clones land. Empty means ~/Projects.
	Root string
	// RemoteURL returns dir's origin remote. Nil means ask git.
	RemoteURL func(dir string) (string, error)
	// Run performs the clone itself. Nil means run `git clone`.
	Run func(ctx context.Context, cloneURL, dest string) error
}

Cloner clones repos into a root directory. The zero value clones into ~/Projects using the git binary; tests substitute the two seams.

func (Cloner) Clone added in v0.3.25 

func (c Cloner) Clone(ctx context.Context, ref RepoRef, dest string) error

Clone clones ref into dest. A failed or cancelled clone leaves nothing behind: whatever git managed to write is removed, and a directory that existed (empty) beforehand is restored empty.

func (Cloner) IsCheckoutOf added in v0.3.25 

func (c Cloner) IsCheckoutOf(dir string, ref RepoRef) bool

IsCheckoutOf reports whether dir is a git checkout whose origin is ref.

func (Cloner) Resolve added in v0.3.25 

func (c Cloner) Resolve(ref RepoRef) (CloneDestination, error)

Resolve picks the directory ref should be cloned into. An existing checkout of the same repo is reused; an unrelated directory of the same name is stepped around ("repo-2"); an existing empty directory is used as-is, because git clones into those happily.

type Finding added in v0.2.40 

type Finding struct {
	Severity Severity
	Message  string
	Detail   string // optional remediation hint
}

Finding is a single diagnostic result from the GitHub auth check.

type LatestRelease 

type LatestRelease struct {
	Version string // e.g. "v0.2.0"
	URL     string // release page URL
}

LatestRelease holds information about the latest GitHub release.

func CLIVersionCheck added in v0.2.33 

func CLIVersionCheck(currentVersion string) *LatestRelease

CLIVersionCheck checks if a newer version is available, using a 24h on-disk cache. Returns the latest release if an upgrade is available, nil otherwise. Skips the check entirely for "dev" builds.

func FetchLatestRelease 

func FetchLatestRelease() *LatestRelease

FetchLatestRelease queries the GitHub API for the latest release. Returns nil if the request fails or no release exists.

type PRCache 

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

PRCache caches PR information to avoid repeated API calls.

func NewPRCache 

func NewPRCache() *PRCache

NewPRCache creates a new PR cache.

func (*PRCache) GetCachedPR 

func (c *PRCache) GetCachedPR(repoDir, branchName string) *PRInfo

GetCachedPR returns cached PR info without fetching. Returns nil if not cached or expired.

func (*PRCache) GetPRForBranch 

func (c *PRCache) GetPRForBranch(repoDir, branchName string) *PRInfo

GetPRForBranch queries GitHub for a PR associated with the given branch. Uses caching to avoid repeated API calls. Returns nil if no PR exists or gh CLI is not available.

func (*PRCache) InvalidateCache 

func (c *PRCache) InvalidateCache(repoDir, branchName string)

InvalidateCache clears the cache for a specific branch.

func (*PRCache) UpdateCacheForRepo 

func (c *PRCache) UpdateCacheForRepo(repoDir string, prsByBranch map[string]*PRInfo)

UpdateCacheForRepo updates the cache with batch-fetched PR data for a repo. This is more efficient than individual fetches.

type PRInfo 

type PRInfo struct {
	Number     int        `json:"number"`
	URL        string     `json:"url"`
	State      PRState    `json:"state"`
	IsDraft    bool       `json:"isDraft"`
	Title      string     `json:"title"`
	CheckState CheckState `json:"checkState"`
	Mergeable  string     `json:"mergeable"` // "MERGEABLE", "CONFLICTING", "UNKNOWN"
	UpdatedAt  time.Time  `json:"updatedAt"`
	Additions  int        `json:"additions"` // Lines added
	Deletions  int        `json:"deletions"` // Lines deleted
}

PRInfo contains information about a pull request.

func UnmarshalPRInfo 

func UnmarshalPRInfo(data string) *PRInfo

UnmarshalPRInfo converts a JSON string from database back to PRInfo.

func (*PRInfo) StatusDescription 

func (p *PRInfo) StatusDescription() string

StatusDescription returns a human-readable description.

func (*PRInfo) StatusIcon 

func (p *PRInfo) StatusIcon() string

StatusIcon returns a unicode icon representing the PR state.

type PRState 

type PRState string

PRState represents the state of a pull request. 

const (
	PRStateOpen   PRState = "OPEN"
	PRStateClosed PRState = "CLOSED"
	PRStateMerged PRState = "MERGED"
	PRStateDraft  PRState = "DRAFT"
)

type RepoRef added in v0.3.25 

type RepoRef struct {
	Host  string // e.g. "github.com"
	Owner string
	Name  string
	// SSH records that the user pasted an ssh URL. We clone back over ssh so
	// their key-based auth keeps working for private repos.
	SSH bool
}

RepoRef identifies a repository on a git host. It is the normalized form of every URL shape a user might paste (https, scp-style ssh, or shorthand).

func ParseRepoRef added in v0.3.25 

func ParseRepoRef(input string) (RepoRef, error)

ParseRepoRef normalizes the repo URL forms people actually paste: 

https://github.com/owner/repo        (with or without .git or a trailing /)
git@github.com:owner/repo.git
ssh://git@github.com/owner/repo.git
github.com/owner/repo
owner/repo

Anything else returns an error whose text names the next step, so it can be shown inline. Nothing is shelled out to git before this succeeds.

func (RepoRef) CloneURL added in v0.3.25 

func (r RepoRef) CloneURL() string

CloneURL is the URL handed to `git clone`.

func (RepoRef) SameRepo added in v0.3.25 

func (r RepoRef) SameRepo(other RepoRef) bool

SameRepo reports whether two refs point at the same repository. Host, owner and name are compared case-insensitively; the transport is ignored, so an https clone matches an ssh remote.

func (RepoRef) Slug added in v0.3.25 

func (r RepoRef) Slug() string

Slug is the "owner/repo" form used in prose and UI copy.

func (RepoRef) String added in v0.3.25 

func (r RepoRef) String() string

String is the slug, qualified with the host when it isn't github.com.

type Severity added in v0.2.40 

type Severity string

Severity ranks a diagnostic finding. 

const (
	SeverityOK    Severity = "ok"
	SeverityWarn  Severity = "warn"
	SeverityError Severity = "error"
)

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.