versions

Documentation

Overview

Package versions resolves a project's upstream version from a pantry recipe's `versions:` specification.

This is deliberately distinct from bottle.PickVersion (which lists pkgx's already-built bottles at dist.pkgx.dev): dist may advertise a normalised version — e.g. ncurses 6.6.0 — that does not exist at the recipe's distributable URL (upstream only ships ncurses-6.5.tar.gz). For a fresh build the version MUST come from the recipe's own `versions:` field so it matches the distributable URL, which interpolates {{version.raw}}.

The logic mirrors libpkgx's usePantry version handling: list a GitHub repo's git tags or its REST Release names, or GET an upstream listing and regex-match version strings, then strip/ignore/select via the loose pkgx-compatible semver.

Index

• func Resolve(spec any, constraint string) (string, string, error)
• type Identity
  • func Identities(spec any) []Identity
• type VersionTag
  • func List(spec any) ([]VersionTag, error)

Functions

func Resolve

func Resolve(spec any, constraint string) (string, string, error)

Resolve returns both the version string (as it appears upstream, for {{version.raw}}) and the raw upstream git tag it was resolved from (for {{version.tag}}) selected from a recipe's `versions:` spec, honouring an optional constraint ("" or "*" = latest). spec is pantry.Recipe.Versions, an `any` unmarshalled from YAML.

The returned tag is the pre-strip candidate that produced the winning version: for the github path it is the `refs/tags/`-trimmed tag (e.g. "v1.2.3" or "openssl-3.5.0"); for the url/match path it is the matched string before any strip. Recipes interpolate it in GitHub release URLs like `.../releases/download/{{version.tag}}/{{version.tag}}.tar.gz`.

A list-form `versions:` (an explicit, hardcoded set of candidate versions) decodes as a []any of the entries' verbatim scalar text (pantry preserves that text so e.g. "3.0" is not coerced to "3"). Those entries ARE the candidates: there is no upstream github/url resolution, no strip/ignore, and the winning candidate is its own {{version.tag}}.

Types

type Identity

type Identity struct {
	// DB is which database can be asked: "GitHub" and "GitLab" for advisories
	// keyed by repository, "npm" for the package ecosystem.
	DB string
	// Name is the key itself: owner/repo, or the package name.
	Name string
}

Identity is a name a vulnerability database can be queried with.

⛔ THE PROBLEM IS THE IDENTITY, NOT THE DATA SOURCE. Measured 2026-10-11: `pkg:pkgx/openssl.org@4.0.2` is known to NO database — OSV answers `{}` to a `pkg:generic/...` purl — while NVD's CPE route answers for anything and answers badly: `cpeName=…openssl:3.5.7` returned 27 CVEs including four from 2009, because those records say `openssl:*` with no upper bound at all.

A recipe already names something better. An offline census over the pantry AND the overlay — 1908 recipes, counting a build dependency on go.dev or rust-lang.org as an ecosystem hint — found 1005 in a package ecosystem and 1506 naming a source repository; only 302 offered nothing but an upstream host, concentrated on a handful (ftp.gnu.org 48, www.x.org 38, sourceforge 29). This turns what a recipe says into the key a database will accept.

⛔ Those are NOT `bk vulnid`'s numbers. It measures something narrower — only what a query can be built from, not what a build dependency hints at — and over the cached pantry alone. See vuln.Table's comment for both.

func Identities

func Identities(spec any) []Identity

Identities returns the keys a `versions:` spec names, sorted and without duplicates.

It walks the same two shapes Resolve does — one source block, or a list of them — because a recipe with several sources names several identities and taking the first would silently drop the others.

It makes NO network call and asserts nothing about whether the key exists upstream: it reports what the recipe claims, which is the half a database query needs before it can be made at all.

type VersionTag

type VersionTag struct {
	Version string
	Tag     string
}

VersionTag pairs a resolved version string (post-strip, v-normalised, as {{version.raw}}) with the pre-strip upstream tag it was resolved from (as {{version.tag}}) — the same two values Resolve returns for a single version.

func List

func List(spec any) ([]VersionTag, error)

List returns EVERY candidate version from a recipe's `versions:` spec — github/gitlab tags, an url+match listing, npm registry keys, or a hardcoded list — with each candidate stripped, CalVer-normalised, ignore-filtered and parsed by the loose semver; unparseable candidates are dropped. The result is deduped by resolved version and sorted DESCENDING (newest first). The spec semantics are identical to Resolve's; List simply keeps all survivors instead of picking the max satisfying a constraint.