enrichment

README

enrichment

A Go library for fetching package metadata from multiple sources using PURLs. It queries the ecosyste.ms API, deps.dev, or package registries directly, and returns a unified PackageInfo struct with license, version, description, repository, and changelog information.

Install

go get github.com/git-pkgs/enrichment

Usage

client, err := enrichment.NewClient()
if err != nil {
    log.Fatal(err)
}

// Look up multiple packages at once
results, err := client.BulkLookup(ctx, []string{
    "pkg:npm/lodash",
    "pkg:pypi/requests",
})

// Get all versions of a package
versions, err := client.GetVersions(ctx, "pkg:npm/lodash")

// Get a specific version
version, err := client.GetVersion(ctx, "pkg:npm/lodash@4.17.21")

By default NewClient uses a hybrid strategy: PURLs with a repository_url qualifier go straight to the registry, everything else goes through ecosyste.ms. Set GIT_PKGS_DIRECT=1 or git config --global pkgs.direct true to skip ecosyste.ms and query all registries directly.

You can also construct a specific client if you want to control the source:

eco, _ := enrichment.NewEcosystemsClient()  // ecosyste.ms API only
reg := enrichment.NewRegistriesClient()      // direct registry queries only
dep := enrichment.NewDepsDevClient()         // deps.dev API only

License

MIT

Documentation

Overview

Package enrichment provides a unified interface for fetching package metadata from external sources (ecosyste.ms API, direct registry queries, deps.dev).

Index

• type Client
  • func NewClient(opts ...Option) (Client, error)
• type DepsDevClient
  • func NewDepsDevClient() *DepsDevClient
  • func (c *DepsDevClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)
  • func (c *DepsDevClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)
  • func (c *DepsDevClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)
• type EcosystemsClient
  • func NewEcosystemsClient() (*EcosystemsClient, error)
  • func (c *EcosystemsClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)
  • func (c *EcosystemsClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)
  • func (c *EcosystemsClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)
• type HybridClient
  • func NewHybridClient() (*HybridClient, error)
  • func (c *HybridClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)
  • func (c *HybridClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)
  • func (c *HybridClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)
• type Option
  • func WithUserAgent(ua string) Option
• type PackageInfo
• type RegistriesClient
  • func NewRegistriesClient() *RegistriesClient
  • func (c *RegistriesClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)
  • func (c *RegistriesClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)
  • func (c *RegistriesClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)
• type VersionInfo

Types

type Client

type Client interface {
	// BulkLookup fetches metadata for multiple packages by PURL.
	// Returns a map of PURL to PackageInfo. Missing packages are omitted.
	BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)

	// GetVersions fetches all versions for a package.
	// The purl should be a package PURL without version (pkg:npm/lodash).
	GetVersions(ctx context.Context, purl string) ([]VersionInfo, error)

	// GetVersion fetches metadata for a specific version.
	// The purl must include a version (pkg:npm/lodash@4.17.21).
	GetVersion(ctx context.Context, purl string) (*VersionInfo, error)
}

Client fetches package metadata from external sources.

func NewClient

func NewClient(opts ...Option) (Client, error)

NewClient creates an enrichment client based on configuration.

By default, uses a hybrid approach:

• PURLs with repository_url qualifier -> direct registry query
• Other PURLs -> ecosyste.ms API

To skip ecosyste.ms and query all registries directly:

• Set GIT_PKGS_DIRECT=1 environment variable, or
• Set git config: git config --global pkgs.direct true

type DepsDevClient

type DepsDevClient struct {
	// contains filtered or unexported fields
}

DepsDevClient queries the deps.dev v3 REST API.

func NewDepsDevClient

func NewDepsDevClient() *DepsDevClient

NewDepsDevClient creates a client for the deps.dev API.

func (*DepsDevClient) BulkLookup

func (c *DepsDevClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)

func (*DepsDevClient) GetVersion

func (c *DepsDevClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)

func (*DepsDevClient) GetVersions

func (c *DepsDevClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)

type EcosystemsClient

type EcosystemsClient struct {
	// contains filtered or unexported fields
}

EcosystemsClient wraps the ecosyste.ms API client.

func NewEcosystemsClient

func NewEcosystemsClient() (*EcosystemsClient, error)

NewEcosystemsClient creates a client that uses the ecosyste.ms API.

func (*EcosystemsClient) BulkLookup

func (c *EcosystemsClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)

func (*EcosystemsClient) GetVersion

func (c *EcosystemsClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)

func (*EcosystemsClient) GetVersions

func (c *EcosystemsClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)

type HybridClient

type HybridClient struct {
	// contains filtered or unexported fields
}

HybridClient routes requests based on PURL qualifiers. PURLs with repository_url go to registries, others go to ecosyste.ms.

func NewHybridClient

func NewHybridClient() (*HybridClient, error)

NewHybridClient creates a client that routes based on PURL qualifiers.

func (*HybridClient) BulkLookup

func (c *HybridClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)

func (*HybridClient) GetVersion

func (c *HybridClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)

func (*HybridClient) GetVersions

func (c *HybridClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)

type Option

type Option func(*options)

Option configures an enrichment client.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header for API requests.

type PackageInfo

type PackageInfo struct {
	Ecosystem         string
	Name              string
	LatestVersion     string
	License           string
	Description       string
	Homepage          string
	Repository        string
	RegistryURL       string
	ChangelogFilename string
	Source            string // "ecosystems", "registries", or "depsdev"
}

PackageInfo contains metadata about a package.

type RegistriesClient

type RegistriesClient struct {
	// contains filtered or unexported fields
}

RegistriesClient queries package registries directly.

func NewRegistriesClient

func NewRegistriesClient() *RegistriesClient

NewRegistriesClient creates a client that queries registries directly.

func (*RegistriesClient) BulkLookup

func (c *RegistriesClient) BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)

func (*RegistriesClient) GetVersion

func (c *RegistriesClient) GetVersion(ctx context.Context, purlStr string) (*VersionInfo, error)

func (*RegistriesClient) GetVersions

func (c *RegistriesClient) GetVersions(ctx context.Context, purlStr string) ([]VersionInfo, error)

type VersionInfo

type VersionInfo struct {
	Number      string
	PublishedAt time.Time
	Integrity   string
	License     string
}

VersionInfo contains metadata about a specific version.