Add docs for asdf, git submodules, vulns and enrichment libraries

Author: andrew

content/docs/coverage.md

@@ -16,6 +16,7 @@ git pkgs ecosystems -f json   # JSON output
 |-----------|-----------|-----------|----------|-------------|----------|
 | Alpine | APKBUILD | | | ✓ | |
 | Arch | PKGBUILD | | | | |
+| asdf | .tool-versions | | | | |
 | Bazel | MODULE.bazel | | | ✓ | |
 | Bower | bower.json | | | ✓ | |
 | Cargo | Cargo.toml | Cargo.lock | ✓ | ✓ | cargo |
@@ -32,6 +33,7 @@ git pkgs ecosystems -f json   # JSON output
 | Docker | Dockerfile, compose.yml | | | ✓ | |
 | Dub | dub.json, dub.sdl | | ✓ | | |
 | Elm | elm.json | | ✓ | ✓ | |
+| Git | .gitmodules | | | | |
 | Go | go.mod | go.sum | ✓ | ✓ | gomod |
 | GitHub Actions | .github/workflows/*.yml | | | ✓ | |
 | Hackage | *.cabal | cabal.project.freeze | ✓ | ✓ | cabal, stack |

content/docs/getting-started.md

@@ -91,6 +91,6 @@ The `--include-submodules` flag works with all commands that scan the working di
 
 ## Supported ecosystems
 
-git-pkgs parses lockfiles from npm, RubyGems, Go, Cargo, pip, Composer, Maven, CocoaPods, Hex, NuGet, Pub, GitHub Actions, and more. Run `git pkgs ecosystems` for the full list.
+git-pkgs parses lockfiles from npm, RubyGems, Go, Cargo, pip, Composer, Maven, CocoaPods, Hex, NuGet, Pub, GitHub Actions, and more. It also recognizes `.tool-versions` (asdf/mise) files and `.gitmodules` for git submodule tracking. Run `git pkgs ecosystems` for the full list.
 
 For best results, commit your lockfiles. Manifests show version ranges but lockfiles show what actually got installed, including transitive dependencies.

content/docs/modules/_index.md

@@ -8,15 +8,19 @@ git-pkgs is built from a set of Go libraries that handle different aspects of de
 - **manifests** parses lockfiles and manifest files to extract dependency information
 - **managers** wraps package manager CLIs behind a common interface for install, add, update, and remove
 - **registries** fetches package metadata from registry APIs
+- **enrichment** combines registry and ecosyste.ms lookups behind a single interface
+- **vulns** queries vulnerability databases (OSV, NVD, GitHub Advisories) with PURL-based lookups
 - **purl** handles Package URL parsing and generation
 - **vers** parses version ranges across different ecosystem syntaxes
 - **spdx** normalizes and validates license expressions
 
 {{< cards >}}
+  {{< card link="enrichment" title="enrichment" subtitle="Package metadata enrichment" >}}
   {{< card link="managers" title="managers" subtitle="Package manager CLI wrapper" >}}
   {{< card link="manifests" title="manifests" subtitle="Manifest and lockfile parsing" >}}
   {{< card link="purl" title="purl" subtitle="Package URL handling" >}}
   {{< card link="registries" title="registries" subtitle="Registry API clients" >}}
   {{< card link="spdx" title="spdx" subtitle="SPDX license utilities" >}}
   {{< card link="vers" title="vers" subtitle="Version range parsing" >}}
+  {{< card link="vulns" title="vulns" subtitle="Vulnerability database queries" >}}
 {{< /cards >}}

content/docs/modules/enrichment.md

@@ -0,0 +1,72 @@
+---
+title: enrichment
+---
+
+A Go library for fetching package metadata from external sources. Combines registry queries and the [ecosyste.ms](https://packages.ecosyste.ms) API behind a single interface.
+
+```go
+import (
+    "context"
+    "github.com/git-pkgs/enrichment"
+)
+
+client, err := enrichment.NewClient()
+if err != nil {
+    panic(err)
+}
+
+info, err := client.BulkLookup(context.Background(), []string{
+    "pkg:npm/lodash@4.17.21",
+    "pkg:pypi/requests@2.31.0",
+})
+
+for purl, pkg := range info {
+    fmt.Printf("%s: latest=%s license=%s\n", purl, pkg.LatestVersion, pkg.License)
+}
+```
+
+## How it works
+
+By default, `NewClient()` returns a hybrid client that routes lookups based on the PURL:
+
+- PURLs with a `repository_url` qualifier go directly to the registry
+- Everything else goes through ecosyste.ms
+
+To skip ecosyste.ms and query all registries directly, set `GIT_PKGS_DIRECT=1` or `git config --global pkgs.direct true`.
+
+## Key types
+
+```go
+type Client interface {
+    BulkLookup(ctx context.Context, purls []string) (map[string]*PackageInfo, error)
+    GetVersions(ctx context.Context, purl string) ([]VersionInfo, error)
+    GetVersion(ctx context.Context, purl string) (*VersionInfo, error)
+}
+
+type PackageInfo struct {
+    Ecosystem     string
+    Name          string
+    LatestVersion string
+    License       string
+    Description   string
+    Homepage      string
+    Repository    string
+    RegistryURL   string
+    Source        string // "ecosystems", "registries", or "depsdev"
+}
+
+type VersionInfo struct {
+    Number      string
+    PublishedAt time.Time
+    Integrity   string
+    License     string
+}
+```
+
+## Installation
+
+```bash
+go get github.com/git-pkgs/enrichment
+```
+
+[View on GitHub](https://github.com/git-pkgs/enrichment)

content/docs/modules/manifests.md

@@ -25,7 +25,7 @@ for _, dep := range result.Dependencies {
 
 ## Supported ecosystems
 
-alpine, arch, bower, brew, cargo, carthage, clojars, cocoapods, composer, conan, conda, cpan, cran, crystal, deno, docker, dub, elm, gem, github-actions, golang, hackage, haxelib, hex, julia, luarocks, maven, nimble, nix, npm, nuget, pub, pypi, rpm, swift, vcpkg.
+alpine, arch, asdf, bower, brew, cargo, carthage, clojars, cocoapods, composer, conan, conda, cpan, cran, crystal, deno, docker, dub, elm, gem, git, github-actions, golang, hackage, haxelib, hex, julia, luarocks, maven, nimble, nix, npm, nuget, pub, pypi, rpm, swift, vcpkg.
 
 ## Types
 

content/docs/modules/vulns.md

@@ -0,0 +1,83 @@
+---
+title: vulns
+---
+
+A Go library for querying vulnerability databases using PURLs. Supports OSV as the primary source, with additional backends for NVD, GitHub Advisories, and others.
+
+```go
+import (
+    "context"
+    "github.com/git-pkgs/purl"
+    "github.com/git-pkgs/vulns/osv"
+)
+
+source := osv.New()
+p := purl.MakePURL("npm", "lodash", "4.17.20")
+
+results, err := source.Query(context.Background(), p)
+if err != nil {
+    panic(err)
+}
+
+for _, v := range results {
+    fmt.Printf("%s (%s): %s\n", v.ID, v.SeverityLevel(), v.Summary)
+    if fixed := v.FixedVersion("npm", "lodash"); fixed != "" {
+        fmt.Printf("  Fixed in: %s\n", fixed)
+    }
+}
+```
+
+## Sources
+
+The `vulns.Source` interface is implemented by multiple backends:
+
+- **osv** -- queries the [OSV API](https://osv.dev) (batch and single queries)
+
+Each source returns results in a common `vulns.Vulnerability` format based on the OSV schema.
+
+## Key types
+
+```go
+type Source interface {
+    Query(ctx context.Context, p *purl.PURL) ([]Vulnerability, error)
+    QueryBatch(ctx context.Context, purls []*purl.PURL) ([][]Vulnerability, error)
+    Get(ctx context.Context, id string) (*Vulnerability, error)
+}
+
+type Vulnerability struct {
+    ID        string
+    Summary   string
+    Details   string
+    Aliases   []string
+    Severity  []Severity
+    Affected  []Affected
+    // ...
+}
+```
+
+## Vulnerability methods
+
+```go
+v.SeverityLevel()                          // "critical", "high", "medium", "low", "unknown"
+v.CVSS()                                   // parsed CVSS info (vector, score, level)
+v.FixedVersion("npm", "lodash")            // first fixed version for a package
+v.IsVersionAffected("npm", "lodash", "4.17.20")  // check if version is affected
+```
+
+## CVSS parsing
+
+The library parses CVSS v2.0, v3.0, v3.1, and v4.0 vectors:
+
+```go
+cvss, err := vulns.ParseCVSS("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H")
+fmt.Printf("Score: %.1f (%s)\n", cvss.Score, cvss.Level)
+// Score: 9.8 (critical)
+```
+
+## Installation
+
+```bash
+go get github.com/git-pkgs/vulns
+```
+
+[View on GitHub](https://github.com/git-pkgs/vulns)

content/docs/vulnerabilities.md

@@ -112,4 +112,6 @@ Your exposure:
 
 ## Data source
 
-Vulnerability data comes from OSV, which aggregates advisories from GitHub (GHSA), NVD (CVE), RustSec, PyPI, Go, and others. Data is cached locally and refreshed when stale (>24h).
+Vulnerability data comes from [OSV](https://osv.dev), which aggregates advisories from GitHub (GHSA), NVD (CVE), RustSec, PyPI, Go, and others. Data is cached locally and refreshed when stale (>24h).
+
+The underlying [`vulns`](/docs/modules/vulns) library handles API queries, CVSS parsing, and affected version matching.