purlkit

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Aug 28, 2026 License: Apache-2.0 Imports: 5 Imported by: 4

Documentation

Overview

Package purlkit is the single home for package-URL behavior in the Bomly SDK (ADR-0038 in bomly-cli's dev-docs/adr). It owns parsing, building, and canonicalizing PURLs — including qualifiers and subpath, which the legacy root helpers cannot represent — the one purl-type mapping table, and the per-ecosystem split of an ecosystem-native name back into org and name.

purlkit is a leaf package: it imports the packageurl library and the standard library only, never the root SDK package, so the root package can delegate to it without an import cycle. Its APIs are therefore string-typed; the typed wrappers live in the root package.

PURL strings are untrusted input (they arrive from lockfiles, SBOM documents, and registry APIs). Every entry point validates and returns errors or zero values; nothing here panics on malformed input.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidPURL = errors.New("invalid package URL")

ErrInvalidPURL reports a package URL that cannot be built or parsed. Every failure from Parse, Build, and their derivatives matches it with errors.Is, including failures surfaced by the underlying parser.

Functions

func Base

func Base(value string) string

Base strips version, qualifiers, and subpath, keeping the package identity (type, namespace, name). It works structurally on the parsed form — replacing the legacy string surgery that cut at the first '?' and the last '@', which mishandled subpath-carrying and version-less package URLs.

func Build

func Build(p PURL) (string, error)

Build normalizes the parts and renders the canonical string form. Type and name are required; qualifiers and subpath are preserved, which the legacy root builder cannot do. The output is a Parse fixed point: structured parts can carry the same renderer-unstable bytes as raw strings, so the single-pass rendering is stabilized before it is returned, and parts that will not stabilize are rejected rather than given an unstable identity.

func Canonical

func Canonical(existing string, p PURL) string

Canonical returns the canonical package URL for a package: the existing string wins when it canonicalizes, otherwise the parts are built — qualifier- and subpath-capable, closing the gap where the legacy fallback chain dropped both. This is the primitive the dependency-level identity rewrite (ADR-0036) wraps.

func CanonicalEcosystem

func CanonicalEcosystem(values ...string) (ecosystem string, ok bool)

CanonicalEcosystem folds the first recognizable value to its canonical Bomly ecosystem token, checking values in the order given (pass ecosystem, then package manager, then package type, so the most authoritative value wins). It returns ok=false when no value is recognized — including for "hex", whose refusal is deliberate.

func Canonicalize

func Canonicalize(value string) string

Canonicalize normalizes a package URL string, returning "" when the value does not parse. Signature-compatible with the root CanonicalizePackageURL.

func EcosystemForType

func EcosystemForType(purlType string) (ecosystem string, ok bool)

EcosystemForType returns the Bomly ecosystem token for a purl type whose spec name differs from the ecosystem token, and refuses ambiguous types. EcosystemForType("hex") returns ("", false) by decision, not omission — see the table comment. Callers that also accept identity mappings (purl types that are themselves Bomly ecosystem tokens, such as "npm") layer their own ecosystem parsing over this table; the kit stays string-typed and does not duplicate the ecosystem vocabulary.

func SplitEcosystemName

func SplitEcosystemName(ecosystem, ecosystemName string) (org, name string)

SplitEcosystemName splits an ecosystem-native package name back into its org and name halves — the inverse of the root Coordinates.EcosystemName join, under the same per-ecosystem rules (bomly-cli ADR-0021): joining is opt-in per ecosystem, so only ecosystems whose advisory databases key on the namespaced form split at all.

The ecosystem argument accepts canonical tokens and their aliases (it is resolved through CanonicalEcosystem). For every ecosystem outside the join list the whole input is the name and org is empty — for OS packages the org is a distro, not part of the package name, and splitting would corrupt identity. A name that does not carry the ecosystem's join shape (an npm name without a scope, a Maven name without a colon) is likewise returned whole: absence of a namespace is data, not an error.

func TypeForValues

func TypeForValues(values ...string) string

TypeForValues maps ecosystem / package-manager / package-type tokens to a package-url type. It is the one authority for this mapping (ADR-0038); the root PackageURLTypeForValues delegates here after converting its typed arguments to strings.

The explicit switch below is consulted for every value before the loose fallback runs, so the most specific mapping wins regardless of the order the caller passes ecosystem / package manager / package type in. The fallback then returns the first non-empty value verbatim, which is only correct where the Bomly identifier happens to be the purl type as well (npm, maven, apk, rpm, ...). Any ecosystem whose purl type differs from its Bomly name needs an explicit case here — without one we emit a type that is not in the purl spec, and consumers keyed on the type (OSV, SBOM ingest) silently fail to match. See bomly-cli issue #317.

Ecosystems that span more than one registry are the exception: erlang covers both Hex (rebar) and OTP (*.app), so it is mapped at the package-manager level only. A bare erlang value with no manager to disambiguate keeps the non-spec pkg:erlang rather than guessing a registry the package may not be published to.

Types

type PURL

type PURL struct {
	Type       string
	Namespace  string
	Name       string
	Version    string
	Qualifiers []Qualifier
	Subpath    string
}

PURL is the structured form of a package URL. Unlike the legacy root builder it carries qualifiers and subpath, so identities such as pkg:maven/g/a@1?type=jar and pkg:golang/m@v1#sub are representable.

func Parse

func Parse(value string) (PURL, error)

Parse parses and validates an untrusted package URL string. The returned value is canonical: qualifier keys are lowercased and sorted, type-specific case rules are applied, and rendering it with String and parsing it again yields the same value. Parse never panics.

func (PURL) String

func (p PURL) String() string

String renders the canonical string form, or "" when the value does not normalize. Use Build when the failure reason matters.

type Qualifier

type Qualifier struct {
	Key   string
	Value string
}

Qualifier is one key/value qualifier of a package URL. Keys are lowercase in canonical form; qualifier lists are sorted by key.

Jump to

Keyboard shortcuts

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