resolver

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package resolver turns a requested source reference into a resolved, immutable revision, keeping requested, resolved, and immutable refs distinct.

Index

Constants

View Source 
const (
	VersionKindRelease = "release" // semver-parseable tag
	VersionKindTag     = "tag"     // non-semver tag
	VersionKindBranch  = "branch"
)

Version kinds for SourceVersion (spec 011 US3).

Variables

View Source 
var ErrNoMatchingVersion = errors.New("no version matches constraint")

ErrNoMatchingVersion is returned when no tag satisfies a version constraint.

View Source 
var ErrUnrewritable = errors.New("declaration shape cannot be rewritten")

ErrUnrewritable reports a declaration shape an upgrade cannot rewrite mechanically without changing its kind.

Functions

func RewriteDeclaration added in v0.7.1 

func RewriteDeclaration(shape DeclarationShape, current string, c Candidate) (key, value string, err error)

RewriteDeclaration returns the manifest key and value that move a declaration of the given shape to candidate while keeping its shape (spec 024 FR-012): a caret range stays a caret range, an exact version stays exact, a tag stays a tag, a commit stays a commit. The current value's spelling — a leading "v" or "=" — is kept.

Types

type Candidate added in v0.7.1 

type Candidate struct {
	Version string
	Tag     string
	Commit  string
}

Candidate is one release an upgrade may move a declaration to.

func FindRelease added in v0.7.1 

func FindRelease(tags []git.TagRef, want string) (Candidate, bool)

FindRelease locates the release named by want among tags: an exact tag name, or a version that parses equal to a tag's version.

func NewestBeyond added in v0.7.1 

func NewestBeyond(tags []git.TagRef, current, constraint string) (Candidate, bool)

NewestBeyond picks the newest release strictly newer than current from tags. Pre-releases are skipped unless the declaration itself names one, so a stable declaration is never offered a beta. current may be empty (a commit pin with no version), in which case the newest release wins.

type Declaration added in v0.7.1 

type Declaration struct {
	Version string
	Ref     string
	Commit  string
	Local   bool
}

Declaration is a skill's tracking intent as the user declared it: at most one of Version, Ref, and Commit drives resolution, with Commit winning over Version and Version over Ref, matching the resolver's own precedence.

type DeclarationShape added in v0.7.1 

type DeclarationShape string

DeclarationShape is the kind of tracking intent a manifest declaration expresses (spec 024 data-model.md §1). It decides whether a normal update may move the skill and how an upgrade rewrites the declaration. 

const (
	ShapeRangeCaret   DeclarationShape = "range-caret"
	ShapeRangeTilde   DeclarationShape = "range-tilde"
	ShapeRangeOther   DeclarationShape = "range-other"
	ShapeExactVersion DeclarationShape = "exact-version"
	ShapeTag          DeclarationShape = "tag"
	ShapeBranch       DeclarationShape = "branch"
	ShapeCommit       DeclarationShape = "commit"
	ShapeLocal        DeclarationShape = "local"
	ShapeUnpinned     DeclarationShape = "unpinned"
)

Declaration shapes. Values are stable: they appear in JSON output and in the lockfile's gskill extension.

func ClassifyDeclaration added in v0.7.1 

func ClassifyDeclaration(d Declaration, refKindHint RefKind) (DeclarationShape, error)

ClassifyDeclaration derives the shape of a declaration. refKindHint is the resolved kind recorded for the skill's ref, when known: whether a ref is a tag or a branch is decided at resolution time, and without a hint a ref is treated as mutable so nothing is ever wrongly reported as pinned.

func (DeclarationShape) Floating added in v0.7.1 

func (s DeclarationShape) Floating() bool

Floating reports whether a normal update may move the skill within the declaration.

func (DeclarationShape) Pinned added in v0.7.1 

func (s DeclarationShape) Pinned() bool

Pinned reports whether the shape fixes one revision, so only a change of intent can move it.

type OutdatedResult 

type OutdatedResult struct {
	Current       string
	Latest        string
	Status        OutdatedStatus
	Informational string
	// LookupErr records a failed remote lookup. With StatusLookupFailed the
	// skill's eligibility is unknown; with a pinned status only the
	// informational newest-release hint is missing.
	LookupErr error
}

OutdatedResult reports a skill's update eligibility. Status is the single source of truth for actionability (StatusUpdateAvailable and nothing else); Latest is the actionable candidate (equal to Current when there is none); Informational names the newest upstream revision that exists outside the requested policy and is never applied by a normal update (FR-004, FR-007).

func Outdated 

func Outdated(ctx context.Context, runner git.Runner, ref source.Ref, req Requested, current Revision) (OutdatedResult, error)

Outdated reports update eligibility for a skill given its current locked revision and the declared intent (spec 018 FR-004/FR-005, spec 024 FR-006). The declaration's shape drives the classification: floating ranges compare against the highest satisfying tag, branch tracking compares the branch head, and exact versions, tags, commits, and local sources are pinned or local states a normal update never moves. A failed remote lookup is a result, not an error, so one dead remote cannot fail a whole plan.

func OutdatedShaped added in v0.7.1 

func OutdatedShaped(ctx context.Context, runner git.Runner, ref source.Ref, shape DeclarationShape, req Requested, current Revision) (OutdatedResult, error)

OutdatedShaped is Outdated with the declaration shape already known.

func (OutdatedResult) Available 

func (r OutdatedResult) Available() bool

Available reports whether a normal update can act on this result.

type OutdatedStatus added in v0.5.1 

type OutdatedStatus string

OutdatedStatus classifies a skill's update eligibility (spec 018 FR-003). 

const (
	StatusUpdateAvailable    OutdatedStatus = "update-available"
	StatusUpToDate           OutdatedStatus = "up-to-date"
	StatusPinnedTag          OutdatedStatus = "pinned-tag"
	StatusPinnedCommit       OutdatedStatus = "pinned-commit"
	StatusLocalSource        OutdatedStatus = "local-source"
	StatusNoCompatibleUpdate OutdatedStatus = "no-compatible-update"
	StatusPinnedVersion      OutdatedStatus = "pinned-version"
	StatusLookupFailed       OutdatedStatus = "lookup-failed"
)

Eligibility statuses. Only StatusUpdateAvailable is actionable by a normal update; every other status explains why the skill cannot move without changing its requested tracking policy.

type RefKind 

type RefKind string

RefKind records how a requested reference was resolved to a revision. 

const (
	RefKindSemver RefKind = "semver"
	RefKindTag    RefKind = "tag"
	RefKindBranch RefKind = "branch"
	RefKindCommit RefKind = "commit"
	RefKindLocal  RefKind = "local"
)

Ref kinds (FR-009, FR-010). semver, tag, and commit are immutable; branch and local are mutable.

func (RefKind) Mutable 

func (k RefKind) Mutable() bool

Mutable reports whether a revision resolved by this kind can change under the same reference over time (branch and local), which triggers a warning (FR-044, SC-008).

func (RefKind) Valid 

func (k RefKind) Valid() bool

Valid reports whether k is a recognized ref kind.

type Requested 

type Requested struct {
	Version string // semver constraint
	Ref     string // branch or tag
	Commit  string // explicit commit
}

Requested is the human's version intent (at most one field drives resolution).

type Revision 

type Revision struct {
	RefKind    RefKind
	Version    string
	Tag        string
	Branch     string
	Commit     string
	MutableRef bool
}

Revision is the resolved, possibly-immutable identity to pin (FR-009, FR-010).

func Resolve 

func Resolve(ctx context.Context, runner git.Runner, ref source.Ref, req Requested) (Revision, []string, error)

Resolve turns a source reference plus requested version into a Revision, returning any advisory warnings (e.g. mutable refs, SC-008). Git sources report the ls-remote round-trip through the context progress sink, so every caller gets resolve progress without emitting its own.

type SourceVersion added in v0.3.0 

type SourceVersion struct {
	Kind   string
	Name   string
	Commit string
}

SourceVersion is one selectable version of a git source.

func ListVersions added in v0.3.0 

func ListVersions(ctx context.Context, runner git.Runner, ref source.Ref) ([]SourceVersion, error)

ListVersions lists a source's selectable versions: release tags in descending semver order, then other tags, then branch heads. Listing failures are returned to the caller — the app layer decides how to degrade (FR-012); the resolver only reports.

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.