enrichment

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, changelog, funding, and maintainer 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

RegistriesClient.GetPackage looks up a single package and, unlike BulkLookup, returns the error when the registry can't be queried.

The ecosyste.ms client can also fan out from a source repository URL to the packages published from that repository and their dependent packages:

groups, err := eco.GetDependentsByRepositoryURL(ctx, "https://github.com/rails/rails", 25, 30)
for _, group := range groups {
    fmt.Printf("%s has %d dependent packages\n", group.PackageName, len(group.Dependents))
}

When ecosyste.ms reports that a package's source repository is a fork, PackageInfo.RepositoryParent holds the declared upstream repository and the host it lives on. It identifies a repository only, so it carries no upstream package, version or commit. It is nil for other packages and for the registries and deps.dev clients.

results, _ := eco.BulkLookup(ctx, []string{"pkg:npm/%40plotly/d3"})
if parent := results["pkg:npm/%40plotly/d3"].RepositoryParent; parent != nil {
    fmt.Println(parent.FullName, parent.HostKind) // d3/d3 github
}

Vulnerabilities, Licenses, and Versions

vulns, err := enrichment.CheckVulnerabilities(ctx, "npm", "lodash", "4.17.20")
for _, vuln := range vulns {
    fmt.Printf("%s: %s fixed in %s\n", vuln.ID, vuln.Severity, vuln.FixedVersion)
}

category := enrichment.CategorizeLicense("MIT OR Apache-2.0") // permissive
outdated := enrichment.IsOutdated("1.0.0", "1.2.0")           // true

Vulnerability checks use OSV by default. License categorization and version comparison are local helpers, so they continue to work in direct/private registry environments.

Scorecard

The scorecard sub-package queries the OpenSSF Scorecard API for repository-level security scores.

client := scorecard.New()
result, err := client.GetScore(ctx, "github.com/lodash/lodash")
fmt.Println(result.Score) // 6.8

End of Life

The endoflife sub-package queries the endoflife.date API for product lifecycle data -- release dates, EOL dates, LTS status, and support windows.

client := endoflife.New()

// All tracked products
products, err := client.GetAllProducts(ctx)

// All release cycles for a product
cycles, err := client.GetProduct(ctx, "nodejs")
for _, c := range cycles {
    fmt.Printf("%s: eol=%v lts=%v\n", c.Name, c.IsEOL(), c.IsLTS())
}

// Single cycle
cycle, err := client.GetCycle(ctx, "python", "3.12")
fmt.Println(cycle.Latest, cycle.IsEOL())

The eol, lts, support, and extendedSupport fields from the API can be either a date or a boolean. The DateOrBool type handles both, and the IsEOL(), IsSupported(), and IsLTS() methods on Cycle do the right thing regardless.

License

MIT.