purlx

Documentation

Overview

Package purlx provides Deputy-specific helpers for working with PURLs.

Deputy relies on github.com/google/osv-scalibr/purl for most parsing and formatting. That package validates PURL types against a fixed allowlist, so this package offers "loose" parsing for emerging types such as pkg:githubactions (see https://github.com/package-url/purl-spec/issues/698).

Index

• Constants
• func AsdfPURL(name, version string) string
• func EquivalentIgnoringVersion(a, b string) bool
• func GitHubActionsPURL(owner, repo, version, subpath string) string
• func GitHubActionsPURLFromPackage(pkg *extractor.Package) string
• func IsGitHubActionsType(t string) bool
• func MisePURL(name, version string) string
• func NPMPackageName(namespace, name string) string
• func ParseLoose(purlStr string) (packageurl.PackageURL, error)

Constants

const (
	// TypeGitHubActions is the emerging PURL type for GitHub Actions dependencies.
	// This matches the package-url spec proposal and existing ecosystem usage.
	TypeGitHubActions = "githubactions"

	// TypeMise is the PURL type for tools managed by mise (mise-en-place):
	// language runtimes and tools installed from mise's many backends (aqua,
	// ubi, cargo, npm, pipx, go, gem, asdf). It matches the value OSV-SCALIBR's
	// upstream runtime/mise extractor uses (purl.TypeMise), so Deputy's mise
	// inventory stays forward-compatible with a future SCALIBR upgrade.
	TypeMise = "mise"

	// TypeAsdf is the PURL type for tools declared in the asdf .tool-versions
	// format. mise also reads .tool-versions, but the format originates with
	// asdf, and OSV-SCALIBR models it as a distinct ecosystem (purl.TypeAsdf)
	// from mise.toml. Deputy emits pkg:asdf for .tool-versions content to stay
	// congruent with that upstream split.
	TypeAsdf = "asdf"
)

Functions

func AsdfPURL

func AsdfPURL(name, version string) string

AsdfPURL formats an asdf PURL (pkg:asdf/<name>@<version>) matching the form emitted by OSV-SCALIBR's runtime/asdf extractor. Returns "" when name is empty.

func EquivalentIgnoringVersion

func EquivalentIgnoringVersion(a, b string) bool

EquivalentIgnoringVersion reports whether a and b refer to the same package, ignoring version and subpath. Comparison is case-insensitive for type, namespace, and name.

func GitHubActionsPURL

func GitHubActionsPURL(owner, repo, version, subpath string) string

GitHubActionsPURL formats a canonical GitHub Actions PURL using namespace (owner), name (repo), optional version (ref), and optional subpath (#...). Subpaths are normalized to be relative and free of traversal.

func GitHubActionsPURLFromPackage

func GitHubActionsPURLFromPackage(pkg *extractor.Package) string

GitHubActionsPURLFromPackage builds a canonical GitHub Actions PURL from a scalibr package. It best-effort reads a "Subpath" string field from pkg.Metadata (when present) to populate the PURL subpath without coupling to a specific metadata type.

func IsGitHubActionsType

func IsGitHubActionsType(t string) bool

IsGitHubActionsType reports whether t is a GitHub Actions-related PURL type. Deputy accepts both the emerging githubactions type and the legacy github type for compatibility.

func MisePURL

func MisePURL(name, version string) string

MisePURL formats a mise PURL for a tool name and version, matching the pkg:mise/<name>@<version> form emitted by OSV-SCALIBR's runtime/mise extractor. The backend, when present, is carried in package metadata rather than the PURL so identity matches upstream. Returns "" when name is empty.

func NPMPackageName

func NPMPackageName(namespace, name string) string

NPMPackageName reassembles an npm package name from a PURL's namespace and name, restoring the "@scope/name" form npm itself uses.

OSV-SCALIBR splits a scoped name into the PURL namespace with its leading "@" already attached, while other PURL producers leave the "@" off, so it is added only when it is missing. An empty namespace means the package is unscoped.

func ParseLoose

func ParseLoose(purlStr string) (packageurl.PackageURL, error)

ParseLoose parses a PURL string without validating the type against a fixed allowlist. It is appropriate for tooling that needs to read PURLs for emerging types.