feat(matchers): declare supported ecosystems on built-in matchers

`sdk.MatcherDescriptor.SupportedEcosystems` existed but no built-in matcher
populated it, and an empty list reads as "all ecosystems". That was wrong for
deps.dev and Grype, which both silently skip packages they cannot map.

- deps.dev now declares the seven ecosystems `depsDevSystem` accepts.
- Grype declares its set per build tag: builtin mode mirrors the
  `ecosystemToSyftType` mapping (19 ecosystems), while external mode stays nil
  because the grype CLI derives coverage from PURLs and is unbounded.
- OSV and Scorecard keep nil, now with comments explaining why that is
  accurate rather than unset: OSV queries by PURL so OSV.dev decides coverage,
  and Scorecard is bounded by GitHub source-repo resolution, not by ecosystem.
- The three auditors document that they are ecosystem-agnostic by construction.

Drift tests keep both declarations in step with the mappings they mirror. The
generated matcher docs now carry an Ecosystems row, and `bomly plugins list`
gains an ECOSYSTEMS column for matchers ("all" when unbounded).

Noted while mapping Grype: apk, dpkg, and rpm packages are typed but reach
Grype without a distro, and its OS matchers are distro-namespace driven, so
they currently match nothing. They are declared because the mapping exists;
plumbing the distro through is left for a separate change.

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

Author: bomly-guy

docs/matchers/depsdev-license-matcher.md

@@ -13,14 +13,15 @@ Fetches package metadata from deps.dev to improve license coverage.
 | Cache behavior | Uses Bomly's matcher cache; cache failures are non-fatal. |
 | Output fields | license value, license source, matched package flag |
 | Tags | `license-enrichment`, `batch-http` |
+| Ecosystems | `npm`, `maven`, `go`, `python`, `dotnet`, `ruby`, `rust` |
 
 ## User notes
 
 Run with `--enrich` when you want license metadata from deps.dev.
 
 ## What `depsdev-license-matcher` does
 
-`depsdev-license-matcher` fetches package metadata from [deps.dev](https://deps.dev) (Google's open package metadata service) and attaches license information to packages that the detector did not resolve a license for. deps.dev coverage is strongest for npm, Go, Maven, NuGet, PyPI, Cargo, and RubyGems.
+`depsdev-license-matcher` fetches package metadata from [deps.dev](https://deps.dev) (Google's open package metadata service) and attaches license information to packages that the detector did not resolve a license for. It covers the ecosystems listed in the table above; packages from any other ecosystem are skipped.
 
 ## When to use it
 

docs/matchers/grype.md

@@ -12,6 +12,7 @@ Uses Grype vulnerability matching against the resolved dependency graph.
 | Uses network | No |
 | Cache behavior | Relies on Grype's local vulnerability database behavior. |
 | Output fields | vulnerability ID, severity, CVSS, fixed version, fix state, EPSS, CWE, known exploitation, risk score, references |
+| Ecosystems | `npm`, `maven`, `scala`, `go`, `python`, `dotnet`, `ruby`, `rust`, `dart`, `elixir`, `erlang`, `php`, `swift`, `haskell`, `r`, `lua`, `apk`, `dpkg`, `rpm` |
 
 ## User notes
 

docs/plugins/how-to-implement-matcher.md

@@ -30,6 +30,15 @@ func (m *matcher) Descriptor(context.Context) (*sdk.MatcherDescriptor, error) {
         DisplayName: "ClearlyDefined License Matcher",
         Aliases:     []string{"clearlydefined", "licenses"},
         Tags:        []string{"license-enrichment", "http", "cache"},
+        // Declare the ecosystems your matcher can actually enrich. Leave this
+        // empty only when the matcher works for every ecosystem — an empty
+        // list reads as "all". `bomly plugins list` and the generated docs
+        // show whatever you put here.
+        SupportedEcosystems: []sdk.Ecosystem{
+            sdk.EcosystemNPM,
+            sdk.EcosystemMaven,
+            sdk.EcosystemGo,
+        },
     }, nil
 }
 

internal/auditors/license/auditor.go

@@ -30,6 +30,9 @@ type Auditor struct {
 
 func (a Auditor) Descriptor() sdk.AuditorDescriptor {
 	return sdk.AuditorDescriptor{
+		// No SupportedEcosystems: policy is evaluated over SPDX license
+		// expressions, whichever ecosystem produced them. Discovering the license
+		// is the matchers' job.
 		Name: auditorName,
 	}
 }

internal/auditors/package/auditor.go

@@ -22,6 +22,9 @@ type Auditor struct {
 
 func (a Auditor) Descriptor() sdk.AuditorDescriptor {
 	return sdk.AuditorDescriptor{
+		// No SupportedEcosystems: deny rules match on package name and group,
+		// and the typosquat corpus is the baseline graph itself rather than a
+		// per-ecosystem package list.
 		Name: auditorName,
 	}
 }

internal/auditors/vulnerability/auditor.go

@@ -17,6 +17,9 @@ type Auditor struct {
 
 func (a Auditor) Descriptor() sdk.AuditorDescriptor {
 	return sdk.AuditorDescriptor{
+		// No SupportedEcosystems: this auditor reads the vulnerability findings
+		// matchers already attached and applies severity and allowlist policy, so
+		// it is ecosystem-agnostic by construction.
 		Name: auditorName,
 	}
 }

internal/cli/plugin_cmd.go

@@ -1091,7 +1091,7 @@ func renderPluginListTables(items []managedplugin.Info, kindFilter pluginKindFil
 		appendTable("Detectors", []string{"ECOSYSTEMS", "PACKAGE MANAGERS", "NAME", "TYPE", "STATE"}, detectorPluginRows(detectors))
 	}
 	if kindFilter.includes(plugschema.PluginKindMatcher) {
-		appendTable("Matchers", []string{"NAME", "TYPE", "STATE"}, basicPluginRows(matchers))
+		appendTable("Matchers", []string{"ECOSYSTEMS", "NAME", "TYPE", "STATE"}, matcherPluginRows(matchers))
 	}
 	if kindFilter.includes(plugschema.PluginKindAuditor) {
 		appendTable("Auditors", []string{"NAME", "TYPE", "STATE"}, basicPluginRows(auditors))
@@ -1120,6 +1120,19 @@ func detectorPluginRows(items []managedplugin.Info) [][]string {
 	return rows
 }
 
+func matcherPluginRows(items []managedplugin.Info) [][]string {
+	rows := make([][]string, 0, len(items))
+	for _, info := range items {
+		rows = append(rows, []string{
+			nonEmptyString(summarizePluginListValue(pluginMatcherEcosystems(info), 6), "-"),
+			pluginListName(info),
+			colorPluginType(pluginTypeValue(info), info),
+			colorPluginState(pluginStateValue(info)),
+		})
+	}
+	return rows
+}
+
 func basicPluginRows(items []managedplugin.Info) [][]string {
 	rows := make([][]string, 0, len(items))
 	for _, info := range items {
@@ -1389,6 +1402,30 @@ func pluginAnalyzerEcosystems(info managedplugin.Info) string {
 	return strings.Join(items, ", ")
 }
 
+// pluginMatcherEcosystems lists the ecosystems a matcher can enrich. Matchers
+// that are not ecosystem-bound declare nothing, which reads as "all" rather
+// than an empty cell.
+func pluginMatcherEcosystems(info managedplugin.Info) string {
+	if info.MatcherDescriptor == nil {
+		return ""
+	}
+	items := make([]string, 0, len(info.MatcherDescriptor.SupportedEcosystems))
+	for _, ecosystem := range info.MatcherDescriptor.SupportedEcosystems {
+		name := strings.TrimSpace(string(ecosystem))
+		if name == "" {
+			continue
+		}
+		if !containsPluginValue(items, name) {
+			items = append(items, name)
+		}
+	}
+	if len(items) == 0 {
+		return "all"
+	}
+	sort.Strings(items)
+	return strings.Join(items, ", ")
+}
+
 func pluginAnalyzerPackageManagers(info managedplugin.Info) string {
 	if info.AnalyzerDescriptor == nil {
 		return ""

internal/cli/plugin_cmd_test.go

@@ -69,8 +69,13 @@ func TestPluginList_KindFilterMatchers(t *testing.T) {
 		t.Fatalf("expected matcher section in output, got:\n%s", text)
 	}
 	matcherHeader := tableHeaderLine(t, render.StripANSI(text), "NAME")
-	assertInOrder(t, matcherHeader, []string{"NAME", "TYPE", "STATE"})
-	for _, omitted := range []string{"ECOSYSTEMS", "PACKAGE MANAGERS", "VERSION"} {
+	assertInOrder(t, matcherHeader, []string{"ECOSYSTEMS", "NAME", "TYPE", "STATE"})
+	// A matcher that declares no ecosystems is not ecosystem-bound, which the
+	// table shows as "all" rather than leaving the cell empty.
+	if !strings.Contains(render.StripANSI(text), "all") {
+		t.Fatalf("expected unrestricted matchers to render ecosystems as %q, got:\n%s", "all", text)
+	}
+	for _, omitted := range []string{"PACKAGE MANAGERS", "VERSION"} {
 		if strings.Contains(text, omitted) {
 			t.Fatalf("expected matcher table to omit %q, got:\n%s", omitted, text)
 		}

internal/matchers/depsdev/matcher.go

@@ -138,6 +138,19 @@ func (c *Checker) Descriptor() sdk.MatcherDescriptor {
 		DisplayName: "deps.dev License Matcher",
 		Aliases:     []string{"deps.dev"},
 		Tags:        []string{"license-enrichment", "batch-http"},
+		// Kept in step with depsDevSystem, which is the set of ecosystems
+		// deps.dev exposes a package system for. Packages from anything else
+		// are skipped, so declaring the list keeps the generated docs and
+		// `bomly plugins list` honest instead of implying full coverage.
+		SupportedEcosystems: []sdk.Ecosystem{
+			sdk.EcosystemNPM,
+			sdk.EcosystemMaven,
+			sdk.EcosystemGo,
+			sdk.EcosystemPython,
+			sdk.EcosystemDotNet,
+			sdk.EcosystemRuby,
+			sdk.EcosystemRust,
+		},
 	}
 }
 

internal/matchers/depsdev/matcher_test.go

@@ -355,3 +355,36 @@ func TestCheckerMatch_EnrichesMissingOnly(t *testing.T) {
 		}
 	}
 }
+
+// The descriptor's ecosystem list is what the generated docs and
+// `bomly plugins list` show, so it has to stay in step with the systems
+// depsDevSystem actually accepts. This catches a new case being added to one
+// without the other.
+func TestDescriptorEcosystemsMatchSupportedSystems(t *testing.T) {
+	all := []sdk.Ecosystem{
+		sdk.EcosystemNPM, sdk.EcosystemMaven, sdk.EcosystemGo, sdk.EcosystemPython,
+		sdk.EcosystemALPM, sdk.EcosystemAPK, sdk.EcosystemCPP, sdk.EcosystemConda,
+		sdk.EcosystemDart, sdk.EcosystemDPKG, sdk.EcosystemElixir, sdk.EcosystemErlang,
+		sdk.EcosystemGitHub, sdk.EcosystemHaskell, sdk.EcosystemHomebrew, sdk.EcosystemLua,
+		sdk.EcosystemDotNet, sdk.EcosystemNix, sdk.EcosystemOCaml, sdk.EcosystemPHP,
+		sdk.EcosystemPortage, sdk.EcosystemProlog, sdk.EcosystemR, sdk.EcosystemRPM,
+		sdk.EcosystemRuby, sdk.EcosystemRust, sdk.EcosystemScala, sdk.EcosystemSBOM,
+		sdk.EcosystemSnap, sdk.EcosystemSwift, sdk.EcosystemTerraform,
+		sdk.EcosystemWordPress, sdk.EcosystemOther,
+	}
+
+	declared := make(map[sdk.Ecosystem]bool)
+	for _, eco := range (&Checker{}).Descriptor().SupportedEcosystems {
+		declared[eco] = true
+	}
+
+	for _, eco := range all {
+		_, supported := depsDevSystem(string(eco))
+		if supported && !declared[eco] {
+			t.Errorf("depsDevSystem accepts %q but the descriptor does not declare it", eco)
+		}
+		if !supported && declared[eco] {
+			t.Errorf("descriptor declares %q but depsDevSystem rejects it", eco)
+		}
+	}
+}