fix(osv): emit spec purl types and make the name fallback reachable

Five ecosystems declared as OSV-supported could never match. Bomly emitted
a purl type outside the spec for each of them, and the name+ecosystem
fallback that would have rescued them was unreachable.

PackageURLTypeForValues consults an explicit switch for every value and
otherwise returns the first non-empty value verbatim, so any ecosystem
without an explicit case leaked its Bomly identifier into the PURL:
pkg:erlang, pkg:haskell, pkg:r, pkg:ocaml, pkg:dpkg. Add explicit cases so
those map to hex, hackage, cran, opam and deb. Verified against the live
OSV API: pkg:cran/commonmark@1.8 and pkg:deb/debian/curl@7.64.0-4 return
advisories where pkg:r/... and pkg:dpkg/... return nothing.

Do the same for the ecosystems that only mapped correctly because the
package manager rescued them (rust, dotnet, dart, elixir, cpp). The
manager is not always populated, so the ecosystem alone now suffices.
Swift is deliberately left out: it is a purl type in its own right, and an
explicit case would beat cocoapods whenever the ecosystem is checked first.

Because SBOM ingest recovers the ecosystem from the purl type via
ParseEcosystem, which only knows Bomly's own identifiers, add an explicit
inverse table so a PURL Bomly emitted still round-trips.

Finally, make the OSV name+ecosystem fallback reachable: buildQuery now
uses it when the canonical PURL's type is not one OSV indexes. Where
neither the type nor the ecosystem is known to OSV, the PURL query is
still sent, so no package loses the query it gets today.

Fixes #317

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: bomly-guy

internal/matchers/osv/matcher.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"github.com/bomly-dev/bomly-cli/internal/logging"
@@ -198,12 +199,6 @@ func (a *Matcher) Descriptor() sdk.MatcherDescriptor {
 		// OSS-Fuzz based rather than a Conan package ecosystem. Julia,
 		// Bitnami, Android, and the Linux kernel are covered by OSV but have
 		// no Bomly ecosystem to map onto.
-		//
-		// erlang, haskell, r, ocaml, and dpkg are listed because OSV indexes
-		// them, but they return nothing today: we emit a PURL type OSV does
-		// not recognise (pkg:erlang rather than pkg:hex, pkg:dpkg rather than
-		// pkg:deb, and so on) and the name-based fallback below is
-		// unreachable. See issue #317.
 		SupportedEcosystems: []sdk.Ecosystem{
 			sdk.EcosystemNPM,
 			sdk.EcosystemMaven,
@@ -505,33 +500,84 @@ func buildQuery(dep *sdk.Dependency, purl string) (cache.Key, BatchQuery, bool)
 		return cache.Key{}, BatchQuery{}, false
 	}
 
-	// Prefer PURL
-	if purl != "" {
+	ecosystem := ecosystemToOSV(string(dep.Ecosystem))
+
+	// Prefer the PURL, but only when OSV can actually resolve its type. A PURL
+	// whose type OSV does not index comes back empty rather than erroring, so
+	// the package looks clean rather than unchecked; a name + ecosystem query
+	// at least gives it a chance. With no ecosystem name to fall back to, the
+	// PURL is still the best (and only) thing we have. See issue #317.
+	if purl != "" && (ecosystem == "" || osvResolvesPURL(purl)) {
 		key := cache.NewKey(purl, "", "", "")
 		purlPkg := PurlPackage{Purl: purl}
 		raw, _ := json.Marshal(purlPkg)
 		return key, BatchQuery{Package: raw}, true
 	}
 
 	// Fall back to name + ecosystem + version
-	ecosystem := ecosystemToOSV(string(dep.Ecosystem))
 	if ecosystem == "" {
 		return cache.Key{}, BatchQuery{}, false
 	}
 
-	key := cache.NewKey("", dep.Name, ecosystem, dep.Version)
-	namePkg := NamePackage{Name: dep.Name, Ecosystem: ecosystem}
+	name := strings.TrimSpace(dep.Name)
+	if name == "" {
+		return cache.Key{}, BatchQuery{}, false
+	}
+
+	key := cache.NewKey("", name, ecosystem, dep.Version)
+	namePkg := NamePackage{Name: name, Ecosystem: ecosystem}
 	raw, _ := json.Marshal(namePkg)
 	return key, BatchQuery{Package: raw, Version: dep.Version}, true
 }
 
+// osvPURLTypes are the package-url types OSV resolves to one of its indexed
+// ecosystems. Anything outside this set (cocoapods, conan, generic, ...) has no
+// OSV ecosystem behind it, so a PURL query for it can only ever come back empty.
+//
+// See https://google.github.io/osv.dev/data/#covered-ecosystems.
+//
+// Distro types (deb, rpm, apk) additionally need the distro namespace to match
+// — pkg:deb/debian/curl@... resolves, pkg:deb/curl@... does not. Container and
+// image scans get that namespace from the upstream PURL; a bare dpkg package
+// with no PURL of its own cannot be matched, and there is no name+ecosystem
+// fallback for it either since OSV keys Debian advisories by release
+// ("Debian:12") rather than by distro alone.
+var osvPURLTypes = map[string]struct{}{
+	"apk":           {},
+	"cargo":         {},
+	"composer":      {},
+	"cran":          {},
+	"deb":           {},
+	"gem":           {},
+	"githubactions": {},
+	"golang":        {},
+	"hackage":       {},
+	"hex":           {},
+	"maven":         {},
+	"npm":           {},
+	"nuget":         {},
+	"opam":          {},
+	"pub":           {},
+	"pypi":          {},
+	"rpm":           {},
+	"swift":         {},
+}
+
+// osvResolvesPURL reports whether OSV indexes the package-url type of purl.
+func osvResolvesPURL(purl string) bool {
+	parsed := sdk.ParsePackageURL(purl)
+	if parsed == nil {
+		return false
+	}
+	_, ok := osvPURLTypes[strings.ToLower(strings.TrimSpace(parsed.Type))]
+	return ok
+}
+
 // ecosystemToOSV maps Bomly ecosystem identifiers to OSV ecosystem names.
 // See: https://ossf.github.io/osv-schema/#affectedpackage-field
 //
-// Currently unreachable: buildQuery only consults this when the PURL is empty,
-// and the caller skips those packages before buildQuery runs. Kept and
-// extended so the mapping is correct for whenever the fallback is revived —
-// see issue #317.
+// Reached from buildQuery whenever the canonical PURL's type is not one OSV
+// indexes, which is the only way a package with a PURL can still be queried.
 func ecosystemToOSV(eco string) string {
 	switch eco {
 	case "npm":

internal/matchers/osv/matcher_test.go

@@ -466,28 +466,82 @@ func TestExtractSeverity_CVSSVectorTakesPrecedenceOverGHSAText(t *testing.T) {
 	}
 }
 
-// Every ecosystem the descriptor claims must have an OSV ecosystem name to go
-// with it, so the declared coverage and the query mapping cannot drift apart.
-// The reverse does not hold: OS ecosystems are queried by PURL rather than by
-// name, so they are declared without appearing in ecosystemToOSV.
+// Every ecosystem the descriptor claims must produce a query OSV can actually
+// resolve — a PURL whose type OSV indexes, or a name + ecosystem pair. A
+// declared ecosystem that produces neither returns empty results rather than
+// erroring, so it looks clean rather than unchecked. See issue #317.
 func TestDeclaredEcosystemsAreQueryable(t *testing.T) {
-	viaPURL := map[sdk.Ecosystem]bool{
-		sdk.EcosystemAPK:  true,
-		sdk.EcosystemDPKG: true,
-		sdk.EcosystemRPM:  true,
-	}
-
 	declared := (&Matcher{}).Descriptor().SupportedEcosystems
 	if len(declared) == 0 {
 		t.Fatal("OSV should declare the ecosystems osv.dev covers")
 	}
 
 	for _, eco := range declared {
-		if viaPURL[eco] {
+		dep := &sdk.Dependency{Coordinates: sdk.Coordinates{
+			Name:      "example",
+			Version:   "1.0.0",
+			Ecosystem: eco,
+		}}
+		purl := sdk.CanonicalPackageURLFromDependency(dep)
+		if purl == "" {
+			t.Errorf("descriptor declares %q but it produces no canonical PURL", eco)
+			continue
+		}
+		if osvResolvesPURL(purl) {
 			continue
 		}
 		if ecosystemToOSV(string(eco)) == "" {
-			t.Errorf("descriptor declares %q but ecosystemToOSV has no name for it", eco)
+			t.Errorf("descriptor declares %q but %q is not an OSV PURL type and ecosystemToOSV has no name for it", eco, purl)
 		}
 	}
 }
+
+// A PURL type OSV does not index must not be sent as a PURL query when a name +
+// ecosystem query is available: OSV answers the unknown type with an empty
+// result rather than an error.
+func TestBuildQueryFallsBackWhenPURLTypeIsNotOSVIndexed(t *testing.T) {
+	dep := &sdk.Dependency{Coordinates: sdk.Coordinates{
+		Name:      "AFNetworking",
+		Version:   "4.0.1",
+		Ecosystem: sdk.EcosystemSwift,
+		PURL:      "pkg:cocoapods/AFNetworking@4.0.1",
+	}}
+
+	_, query, ok := buildQuery(dep, sdk.CanonicalPackageURLFromDependency(dep))
+	if !ok {
+		t.Fatal("expected a query to be built")
+	}
+	var namePkg NamePackage
+	if err := json.Unmarshal(query.Package, &namePkg); err != nil {
+		t.Fatalf("expected NamePackage JSON: %v", err)
+	}
+	if namePkg.Ecosystem != "SwiftURL" {
+		t.Errorf("Ecosystem = %q, want %q", namePkg.Ecosystem, "SwiftURL")
+	}
+	if query.Version != "4.0.1" {
+		t.Errorf("Version = %q, want %q", query.Version, "4.0.1")
+	}
+}
+
+// When neither the PURL type nor the ecosystem is known to OSV, keep sending
+// the PURL: it costs one slot in a batch we are already making, and dropping
+// the package would lose the only signal we have.
+func TestBuildQueryKeepsPURLWhenNoEcosystemName(t *testing.T) {
+	dep := &sdk.Dependency{Coordinates: sdk.Coordinates{
+		Name:      "zlib",
+		Version:   "1.3",
+		Ecosystem: sdk.EcosystemCPP,
+	}}
+
+	_, query, ok := buildQuery(dep, sdk.CanonicalPackageURLFromDependency(dep))
+	if !ok {
+		t.Fatal("expected a query to be built")
+	}
+	var purlPkg PurlPackage
+	if err := json.Unmarshal(query.Package, &purlPkg); err != nil {
+		t.Fatalf("expected PurlPackage JSON: %v", err)
+	}
+	if purlPkg.Purl != "pkg:conan/zlib@1.3" {
+		t.Errorf("PURL = %q, want %q", purlPkg.Purl, "pkg:conan/zlib@1.3")
+	}
+}

internal/sbom/identity.go

@@ -11,11 +11,40 @@ func parsePURL(value string) *packageurl.PackageURL {
 	return sdk.ParsePackageURL(strings.TrimSpace(value))
 }
 
+// purlTypeEcosystems inverts sdk.PackageURLTypeForValues for the purl types
+// whose spec name differs from the Bomly ecosystem name. Without these, a PURL
+// Bomly itself emitted would not round-trip through SBOM ingest: ParseEcosystem
+// only knows Bomly's own identifiers.
+var purlTypeEcosystems = map[string]sdk.Ecosystem{
+	"golang": sdk.EcosystemGo,
+	// Elixir and Erlang share pkg:hex; Elixir is the far more common source of
+	// a hex PURL, and the component's own ecosystem field wins when present.
+	"hex":       sdk.EcosystemElixir,
+	"hackage":   sdk.EcosystemHaskell,
+	"cran":      sdk.EcosystemR,
+	"opam":      sdk.EcosystemOCaml,
+	"deb":       sdk.EcosystemDPKG,
+	"cargo":     sdk.EcosystemRust,
+	"nuget":     sdk.EcosystemDotNet,
+	"pypi":      sdk.EcosystemPython,
+	"gem":       sdk.EcosystemRuby,
+	"composer":  sdk.EcosystemPHP,
+	"pub":       sdk.EcosystemDart,
+	"conan":     sdk.EcosystemCPP,
+	"cocoapods": sdk.EcosystemSwift,
+	"swift":     sdk.EcosystemSwift,
+	// pkg:maven covers Scala too, but Java is the overwhelmingly common case
+	// and there is nothing in the PURL to tell them apart.
+	"maven":         sdk.EcosystemMaven,
+	"githubactions": sdk.EcosystemGitHub,
+}
+
 func ecosystemFromPURLType(purlType string) sdk.Ecosystem {
 	normalized := strings.ToLower(strings.TrimSpace(purlType))
+	if ecosystem, ok := purlTypeEcosystems[normalized]; ok {
+		return ecosystem
+	}
 	switch normalized {
-	case "golang":
-		return sdk.EcosystemGo
 	case "":
 		return sdk.EcosystemUnknown
 	default:

internal/sbom/sbom_test.go

@@ -728,3 +728,21 @@ func mustSyftJSONFixture(t *testing.T) []byte {
 	}
 	return []byte(strings.TrimSpace(out.String()))
 }
+
+// A PURL Bomly emitted must name an ecosystem Bomly recognises when it is read
+// back in. ParseEcosystem only knows Bomly's own identifiers, so every purl
+// type whose spec name differs from the ecosystem name (pkg:deb for dpkg,
+// pkg:cran for r, ...) needs an entry in purlTypeEcosystems. See issue #317.
+func TestEcosystemFromPURLTypeRoundTripsEmittedPURLs(t *testing.T) {
+	for _, manager := range sdk.AllPackageManagers() {
+		ecosystem := manager.Ecosystem()
+		if ecosystem == sdk.EcosystemUnknown {
+			continue
+		}
+		purlType := sdk.PackageURLTypeForValues(ecosystem, manager)
+		got := ecosystemFromPURLType(purlType)
+		if got == sdk.EcosystemUnknown {
+			t.Errorf("ecosystemFromPURLType(%q) = unknown; %q packages would lose their ecosystem on SBOM ingest", purlType, ecosystem)
+		}
+	}
+}

sdk/package_manager_test.go

@@ -135,6 +135,78 @@ func TestPackageURLTypeForGitHubActions(t *testing.T) {
 	}
 }
 
+// Every declared ecosystem must resolve to a type that exists in the purl spec.
+// Without an explicit case the fallback returns the Bomly identifier verbatim,
+// which produced pkg:erlang / pkg:haskell / pkg:r / pkg:ocaml / pkg:dpkg and
+// made those packages unmatchable downstream. See issue #317.
+func TestPackageURLTypeForValuesUsesSpecTypes(t *testing.T) {
+	cases := []struct {
+		ecosystem Ecosystem
+		manager   PackageManager
+		want      string
+	}{
+		{EcosystemErlang, PackageManagerRebar, "hex"},
+		{EcosystemErlang, PackageManagerOTP, "hex"},
+		{EcosystemElixir, PackageManagerMix, "hex"},
+		{EcosystemHaskell, PackageManagerCabal, "hackage"},
+		{EcosystemHaskell, PackageManagerStack, "hackage"},
+		{EcosystemR, PackageManagerRPackage, "cran"},
+		{EcosystemOCaml, PackageManagerOpam, "opam"},
+		{EcosystemDPKG, PackageManagerDPKG, "deb"},
+
+		// Regression guards for the ecosystems that already mapped correctly.
+		{EcosystemNPM, PackageManagerNPM, "npm"},
+		{EcosystemGo, PackageManagerGoMod, "golang"},
+		{EcosystemPython, PackageManagerPip, "pypi"},
+		{EcosystemMaven, PackageManagerMaven, "maven"},
+		{EcosystemScala, PackageManagerSBT, "maven"},
+		{EcosystemRust, PackageManagerCargo, "cargo"},
+		{EcosystemRuby, PackageManagerBundler, "gem"},
+		{EcosystemPHP, PackageManagerComposer, "composer"},
+		{EcosystemDotNet, PackageManagerNuGet, "nuget"},
+		{EcosystemDart, PackageManagerPub, "pub"},
+		{EcosystemSwift, PackageManagerSwiftPM, "swift"},
+		{EcosystemSwift, PackageManagerCocoaPods, "cocoapods"},
+		{EcosystemCPP, PackageManagerConan, "conan"},
+		{EcosystemAPK, PackageManagerAPK, "apk"},
+		{EcosystemRPM, PackageManagerRPM, "rpm"},
+		{EcosystemGitHub, PackageManagerGitHubActions, "githubactions"},
+	}
+
+	for _, tc := range cases {
+		if got := PackageURLTypeForValues(tc.ecosystem, tc.manager); got != tc.want {
+			t.Errorf("PackageURLTypeForValues(%q, %q) = %q, want %q", tc.ecosystem, tc.manager, got, tc.want)
+		}
+	}
+}
+
+// The package manager is not always populated (SBOM ingest, syft-sourced
+// container packages), so the ecosystem alone has to be enough to reach a purl
+// type in the spec. CocoaPods is the one exception: it shares the swift
+// ecosystem, and swift is itself a valid purl type.
+func TestPackageURLTypeForEcosystemAlone(t *testing.T) {
+	specTypes := map[string]bool{
+		"apk": true, "cargo": true, "cocoapods": true, "composer": true,
+		"conan": true, "cran": true, "deb": true, "gem": true,
+		"githubactions": true, "golang": true, "hackage": true, "hex": true,
+		"maven": true, "npm": true, "nuget": true, "opam": true,
+		"pub": true, "pypi": true, "rpm": true, "swift": true,
+	}
+
+	for _, manager := range AllPackageManagers() {
+		ecosystem := manager.Ecosystem()
+		withManager := PackageURLTypeForValues(ecosystem, manager)
+		if !specTypes[withManager] {
+			// Ecosystems Bomly reports but the purl spec has no type for
+			// (conda, homebrew, nix, ...) are out of scope here.
+			continue
+		}
+		if got := PackageURLTypeForValues(ecosystem); got != withManager && ecosystem != EcosystemSwift {
+			t.Errorf("PackageURLTypeForValues(%q) = %q, want %q (as with manager %q)", ecosystem, got, withManager, manager)
+		}
+	}
+}
+
 func TestAllPackageManagersReturnsCopy(t *testing.T) {
 	managers := AllPackageManagers()
 	if len(managers) == 0 {