ghpr

Documentation

Overview

Package ghpr fetches the lockfile changes of a GitHub pull request via the REST API, so a PR can be vetted without cloning the repository.

Index

• Constants
• Variables
• func HasToken() bool
• func ParseCommit(s string) (owner, repo, sha string, ok bool)
• func PostComment(ref Ref, body string) (commentURL string, updated bool, err error)
• func SplitBasehead(s string) (base, head string, ok bool)
• func Token() string
• type ChangedFile
• type CmpRef
  • func ParseCompare(s string) (CmpRef, bool)
  • func ResolveCommit(owner, repo, sha string) (CmpRef, error)
  • func (r CmpRef) String() string
• type QueueItem
  • func ListQueue(scope string, authors []string, limit int) ([]QueueItem, string, error)
• type Ref
  • func Parse(s string) (Ref, bool)
  • func (r Ref) String() string
• type Result
  • func Fetch(ref Ref, isLockfile func(path string) bool) (*Result, error)
  • func FetchCompare(ref CmpRef, isLockfile func(path string) bool) (*Result, error)

Constants

const CommentMarker = "<!-- lockvet-report -->"

CommentMarker prefixes every comment lockvet posts, so reruns update the existing comment instead of stacking new ones. The lockvet GitHub Action uses the same marker — CLI and Action never duplicate each other.

Variables

var DefaultQueueAuthors = []string{"app/dependabot", "app/renovate"}

DefaultQueueAuthors are the bot identities searched for when the user doesn't pass -author. The app/ prefix matches GitHub App bot accounts (dependabot[bot], renovate[bot]).

Functions

func HasToken

func HasToken() bool

HasToken reports whether a GitHub token is available (env or gh CLI).

func ParseCommit

func ParseCommit(s string) (owner, repo, sha string, ok bool)

ParseCommit recognises a GitHub commit URL:

https://github.com/OWNER/REPO/commit/SHA

func PostComment

func PostComment(ref Ref, body string) (commentURL string, updated bool, err error)

PostComment creates — or, if a lockvet comment already exists, updates — the report comment on a pull request. Returns the comment's URL and whether an existing comment was updated. Requires an authenticated token.

func SplitBasehead

func SplitBasehead(s string) (base, head string, ok bool)

SplitBasehead splits "BASE...HEAD" (or "BASE..HEAD") into its two sides.

func Token

func Token() string

Token exposes the discovered GitHub token (or "") to other packages that talk to the GitHub API, e.g. the release-notes fetcher.

Types

type ChangedFile

type ChangedFile struct {
	Path string
	Old  []byte
	New  []byte
}

ChangedFile is one lockfile touched by the PR, with contents on both sides. Old is nil for added files, New is nil for removed ones.

type CmpRef

type CmpRef struct {
	Owner string
	Repo  string
	Base  string
	Head  string
}

CmpRef identifies a comparison between two revisions of a repository. Head may use GitHub's fork syntax ("user:branch" or "user:repo:branch").

func ParseCompare

func ParseCompare(s string) (CmpRef, bool)

ParseCompare recognises a GitHub compare URL:

https://github.com/OWNER/REPO/compare/BASE...HEAD

BASE and HEAD may be branches (slashes ok), tags, or SHAs; HEAD may use fork syntax (user:branch). Trailing ?query or #fragment is ignored.

func ResolveCommit

func ResolveCommit(owner, repo, sha string) (CmpRef, error)

ResolveCommit turns OWNER/REPO + SHA into the CmpRef parent...sha, so a single commit can be vetted with FetchCompare.

func (CmpRef) String

func (r CmpRef) String() string

type QueueItem

type QueueItem struct {
	Ref     Ref
	Title   string
	Author  string // e.g. "dependabot[bot]"
	URL     string // html_url
	Updated time.Time
}

QueueItem is one open dependency-update pull request found by ListQueue.

func ListQueue

func ListQueue(scope string, authors []string, limit int) ([]QueueItem, string, error)

ListQueue finds open pull requests by the given authors in scope, which is either "owner/repo" or a user/org name. Authors may be empty ("any") to match every open PR. Results are most-recently-updated first, capped at limit. The returned string describes the search scope (e.g. "org:grafana") for display.

type Ref

type Ref struct {
	Owner  string
	Repo   string
	Number int
}

Ref identifies a pull request.

func Parse

func Parse(s string) (Ref, bool)

Parse recognises a PR reference in either form:

https://github.com/OWNER/REPO/pull/123   (with or without scheme/suffix)
OWNER/REPO#123

func (Ref) String

func (r Ref) String() string

type Result

type Result struct {
	Files     []ChangedFile
	BaseLabel string // e.g. "main"
	HeadLabel string // e.g. "PR #123 (dependabot/cargo/jiff-0.1.14)"
	Title     string
	Warnings  []string

	// CIHost is the CI instance host the fetched files run their
	// pipelines on, when the fetch context knows it. Only the GitLab
	// fetchers (internal/glmr) fill it: an MR/compare URL names the
	// instance, so `$CI_SERVER_FQDN/...` component pins in fetched
	// .gitlab-ci.yml files can be resolved against that host instead
	// of staying claim-free. Empty everywhere else.
	CIHost string
}

Result is everything needed to diff and label a PR or comparison.

func Fetch

func Fetch(ref Ref, isLockfile func(path string) bool) (*Result, error)

Fetch downloads the PR metadata and the before/after contents of every changed file whose basename isLockfile accepts. It authenticates with GITHUB_TOKEN / GH_TOKEN when set (or a logged-in `gh` CLI), and works unauthenticated on public repos otherwise.

func FetchCompare

func FetchCompare(ref CmpRef, isLockfile func(path string) bool) (*Result, error)

FetchCompare downloads the file changes between two revisions via the GitHub compare API (three-dot semantics: changes are relative to the merge base, exactly like a PR diff) and returns the before/after contents of every changed file isLockfile accepts.