Documentation
¶
Overview ¶
Package tag lists tags, classifies versions, and applies release cooldown.
Index ¶
- func FormatTagAge(isoDate string) string
- func URL(owner, repo, tag string) string
- type CooldownConfig
- type Info
- type Lister
- func (tl *Lister) BestAncestorTag(ctx context.Context, owner, repo, sha string) (string, error)
- func (tl *Lister) BestPatchTagForSHA(ctx context.Context, owner, repo, sha string) (string, error)
- func (tl *Lister) BranchHeadSHA(ctx context.Context, owner, repo, branch string) (string, error)
- func (tl *Lister) CuratePickerTags(ctx context.Context, owner, repo, pinnedSHA string) ([]PickerTag, error)
- func (tl *Lister) GetRepoInfo(ctx context.Context, owner, repo string) (*RepoInfo, error)
- func (tl *Lister) LatestStableTag(ctx context.Context, owner, repo string) (string, error)
- func (tl *Lister) ListTags(ctx context.Context, owner, repo string) ([]Info, error)
- func (tl *Lister) LookupTag(ctx context.Context, owner, repo, tagName string) *Info
- func (tl *Lister) ReleaseDate(owner, repo, tag string) string
- func (tl *Lister) SuggestTagsForSHA(ctx context.Context, owner, repo, sha string) ([]Suggestion, error)
- func (tl *Lister) TagsForSHA(ctx context.Context, owner, repo, sha string) ([]Info, error)
- func (tl *Lister) UniquePatchTagForRef(ctx context.Context, owner, repo, sha, ref string) (string, error)
- type PickerTag
- type ReleaseInfo
- type RepoInfo
- type Suggestion
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatTagAge ¶
FormatTagAge returns a relative age string like "3d ago" from an ISO 8601 timestamp.
Types ¶
type CooldownConfig ¶
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 ¶
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 ¶
NewListerForTest builds a Lister wired to a mock registry.
func (*Lister) BestAncestorTag ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
LookupTag returns the Info for a specific tag name, or nil if not found. Uses the cached tag list from ListTags.
func (*Lister) ReleaseDate ¶
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 ¶
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 ¶
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 ¶
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.