tag

package
v0.1.6-rc.2 Latest Latest
Warning

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

Go to latest
Published: Jul 27, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package tag lists tags, classifies versions, and applies release cooldown.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatTagAge

func FormatTagAge(isoDate string) string

FormatTagAge returns a relative age string like "3d ago" from an ISO 8601 timestamp.

func URL

func URL(owner, repo, tag string) string

URL returns a clickable GitHub releases tag URL.

Types

type CooldownConfig

type CooldownConfig struct {
	DefaultDays   int
	RepoOverrides map[string]int
}

CooldownConfig controls the minimum age threshold for tag upgrade suggestions.

func (CooldownConfig) CooldownDays

func (c CooldownConfig) CooldownDays(owner, repo string) int

CooldownDays returns the cooldown period for a repo, falling back to the default.

func (CooldownConfig) CooldownDuration

func (c CooldownConfig) CooldownDuration(owner, repo string) time.Duration

CooldownDuration returns the cooldown as a time.Duration.

type Info

type Info struct {
	Name        string // e.g. "v4.2.2"
	SHA         string // commit SHA the tag points to (dereferenced for annotated tags)
	IsRelease   bool   // true if a GitHub Release exists for this tag
	IsImmutable bool   // true if the release is marked immutable (tag can't be moved/deleted)
	IsMajor     bool   // true if this looks like a major-only tag (e.g. "v4")
}

Info represents a tag with optional release metadata.

func (Info) MatchesSHA

func (t Info) MatchesSHA(sha string) bool

MatchesSHA reports whether sha names this tag's commit. Resolution peels annotated tags to the commit (^{commit}) before a SHA is ever written, so a tag is identified by its commit SHA alone.

type Lister

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

Lister fetches tags and release metadata for action repos.

Safe for concurrent use. The caches are syncmap.Map (the same primitive ghapi.Client and resolve.Resolver use); network fetches run outside any lock and are deduplicated per-repo via singleflight, so workers fetching different repos run in parallel while concurrent calls for the same repo collapse into one request.

func NewLister

func NewLister(client *ghapi.Client, cooldown CooldownConfig) *Lister

NewLister creates a Lister with the given API client and cooldown config.

func NewListerForTest

func NewListerForTest(t *testing.T, reg *httpmock.Registry) *Lister

NewListerForTest builds a Lister wired to a mock registry.

func (*Lister) BestAncestorTag

func (tl *Lister) BestAncestorTag(ctx context.Context, owner, repo, sha string) (string, error)

BestAncestorTag returns the latest full-semver tag that is an ancestor of the given SHA. Used when no tag points at the exact SHA but the repo follows semver release conventions — we walk back to the nearest release. Checks at most 3 candidate tags (latest first) to limit API calls.

func (*Lister) BestPatchTagForSHA

func (tl *Lister) BestPatchTagForSHA(ctx context.Context, owner, repo, sha string) (string, error)

BestPatchTagForSHA returns the highest full-semver patch tag pointing at the given SHA, or "" if none exists. This is used to narrow mutable version refs (like "v4") to a specific patch version (like "v4.2.1") when pinning.

func (*Lister) BranchHeadSHA

func (tl *Lister) BranchHeadSHA(ctx context.Context, owner, repo, branch string) (string, error)

BranchHeadSHA returns the latest commit SHA on the given branch.

func (*Lister) CuratePickerTags

func (tl *Lister) CuratePickerTags(ctx context.Context, owner, repo, pinnedSHA string) ([]PickerTag, error)

CuratePickerTags returns a short list of the most useful tags for a picker. Shows the latest patch per major version (up to 3 majors), marks the one matching pinnedSHA as "installed", and only puts 📦 on that one.

func (*Lister) GetRepoInfo

func (tl *Lister) GetRepoInfo(ctx context.Context, owner, repo string) (*RepoInfo, error)

GetRepoInfo fetches repository visibility and default branch. Cached per owner/repo. Concurrent calls for different repos run in parallel; calls for the same repo are coalesced via singleflight.

func (*Lister) LatestStableTag

func (tl *Lister) LatestStableTag(ctx context.Context, owner, repo string) (string, error)

LatestStableTag returns the latest non-major stable tag that passes cooldown. It skips major-only tags (e.g. "v4"), pre-release tags, and tags younger than the cooldown period. Returns ("", nil) if no suitable tag is found.

func (*Lister) ListTags

func (tl *Lister) ListTags(ctx context.Context, owner, repo string) ([]Info, error)

ListTags fetches tags for an action repo, enriched with release metadata. Results are cached per owner/repo. Network IO runs without the cache mutex held; concurrent calls for the same repo are coalesced via singleflight, so multiple pin workers fetching different repos proceed in parallel.

func (*Lister) LookupTag

func (tl *Lister) LookupTag(ctx context.Context, owner, repo, tagName string) *Info

LookupTag returns the Info for a specific tag name, or nil if not found. Uses the cached tag list from ListTags.

func (*Lister) ReleaseDate

func (tl *Lister) ReleaseDate(owner, repo, tag string) string

ReleaseDate returns the published_at date for a tag, if available.

func (*Lister) SuggestTagsForSHA

func (tl *Lister) SuggestTagsForSHA(ctx context.Context, owner, repo, sha string) ([]Suggestion, error)

SuggestTagsForSHA returns a curated set of tag suggestions for a pinned SHA. It includes exact-match tags, plus major/minor family alternatives when the match is version-like. Returns at most 5 suggestions.

func (*Lister) TagsForSHA

func (tl *Lister) TagsForSHA(ctx context.Context, owner, repo, sha string) ([]Info, error)

TagsForSHA returns all tags whose commit SHA matches the given SHA.

func (*Lister) UniquePatchTagForRef

func (tl *Lister) UniquePatchTagForRef(ctx context.Context, owner, repo, sha, ref string) (string, error)

UniquePatchTagForRef returns the sole full-semver patch tag that matches the given ref's family, or "" if the choice is ambiguous (0 or 2+ candidates). For "v9" it only considers v9.x.y tags; for "v4.2" only v4.2.x tags. This is used for auto-pinning: if there's exactly one obvious patch tag, we can pin without prompting.

type PickerTag

type PickerTag struct {
	Tag       Info
	Label     string // formatted display label
	Installed bool   // true if this tag matches the currently pinned SHA
}

PickerTag is a tag formatted for the interactive picker.

type ReleaseInfo

type ReleaseInfo struct {
	TagName     string
	PublishedAt string // ISO 8601 date
}

ReleaseInfo holds release metadata for a tag.

type RepoInfo

type RepoInfo struct {
	DefaultBranch string // e.g. "main"
	Visibility    string // "public", "private", or "internal"
	PushedAt      string // ISO 8601 timestamp of last push
}

RepoInfo holds repository metadata relevant for pinning decisions.

func (RepoInfo) IsInternal

func (ri RepoInfo) IsInternal() bool

IsInternal returns true for private or internal repos — those where pinning to the default branch is a reasonable option.

type Suggestion

type Suggestion struct {
	Tag       Info
	Reason    string
	Preferred bool // true if this tag points directly at the pinned SHA
}

Suggestion is a tag paired with why it's being suggested.

func ReorderSuggestions

func ReorderSuggestions(suggestions []Suggestion) []Suggestion

ReorderSuggestions puts full semver tags first (recommended for pinning), then major-only tags last. Within full semver: immutable releases first, then regular releases, then plain tags.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL