Add support for programmatically listing catalogers

syft/exp/cataloger.go

@@ -0,0 +1,106 @@
+package exp
+
+import (
+	"fmt"
+	"sort"
+
+	"github.com/anchore/syft/internal/capabilities"
+	"github.com/anchore/syft/internal/task"
+	"github.com/anchore/syft/syft/cataloging"
+	"github.com/anchore/syft/syft/cataloging/pkgcataloging"
+)
+
+// Cataloger describes an available cataloger and its selection metadata.
+type Cataloger struct {
+	Name string   `json:"name"`
+	Tags []string `json:"tags"`
+}
+
+// AllCatalogers returns information about all registered catalogers
+// (both package and file catalogers), sorted by name. Any additional
+// user-provided cataloger references are included in the result.
+func AllCatalogers(additional ...pkgcataloging.CatalogerReference) ([]Cataloger, error) {
+	return SelectCatalogers(cataloging.SelectionRequest{
+		DefaultNamesOrTags: []string{"all"},
+	}, additional...)
+}
+
+// SelectCatalogers returns information about catalogers matching the given
+// selection request. It applies the same selection logic used by CreateSBOM
+// and the "syft cataloger list" CLI command.
+//
+// Any additional user-provided cataloger references are merged into the
+// selectable set before selection is applied. References with AlwaysEnabled
+// set to true are always included in the result regardless of the selection.
+//
+// If the selection request is empty (zero value), no catalogers are returned;
+// use AllCatalogers() or pass a selection with DefaultNamesOrTags: []string{"all"}.
+func SelectCatalogers(selection cataloging.SelectionRequest, additional ...pkgcataloging.CatalogerReference) ([]Cataloger, error) {
+	cfg := task.DefaultCatalogingFactoryConfig()
+
+	pkgTasks, err := task.DefaultPackageTaskFactories().Tasks(cfg)
+	if err != nil {
+		return nil, fmt.Errorf("unable to create package cataloger tasks: %w", err)
+	}
+
+	fileTasks, err := task.DefaultFileTaskFactories().Tasks(cfg)
+	if err != nil {
+		return nil, fmt.Errorf("unable to create file cataloger tasks: %w", err)
+	}
+
+	var persistentTasks []task.Task
+	for _, ref := range additional {
+		if ref.Cataloger == nil {
+			continue
+		}
+		t := task.NewPackageTask(cfg, ref.Cataloger, ref.Tags...)
+		if ref.AlwaysEnabled {
+			persistentTasks = append(persistentTasks, t)
+		} else {
+			pkgTasks = append(pkgTasks, t)
+		}
+	}
+
+	if selection.IsEmpty() {
+		if len(persistentTasks) > 0 {
+			return extractCatalogers(persistentTasks), nil
+		}
+		return nil, nil
+	}
+
+	taskGroups := [][]task.Task{pkgTasks, fileTasks}
+	selectedGroups, _, err := task.SelectInGroups(taskGroups, selection)
+	if err != nil {
+		return nil, fmt.Errorf("unable to select catalogers: %w", err)
+	}
+
+	var selected []task.Task
+	for _, group := range selectedGroups {
+		selected = append(selected, group...)
+	}
+	selected = append(selected, persistentTasks...)
+
+	return extractCatalogers(selected), nil
+}
+
+func extractCatalogers(tasks []task.Task) []Cataloger {
+	infos := capabilities.ExtractCatalogerInfo(tasks)
+
+	catalogers := make([]Cataloger, 0, len(infos))
+	for _, info := range infos {
+		tags := info.Selectors
+		if tags == nil {
+			tags = []string{}
+		}
+		catalogers = append(catalogers, Cataloger{
+			Name: info.Name,
+			Tags: tags,
+		})
+	}
+
+	sort.Slice(catalogers, func(i, j int) bool {
+		return catalogers[i].Name < catalogers[j].Name
+	})
+
+	return catalogers
+}

syft/exp/cataloger_test.go

@@ -0,0 +1,151 @@
+package exp
+
+import (
+	"context"
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/anchore/syft/syft/artifact"
+	"github.com/anchore/syft/syft/cataloging"
+	"github.com/anchore/syft/syft/cataloging/pkgcataloging"
+	"github.com/anchore/syft/syft/file"
+	"github.com/anchore/syft/syft/pkg"
+)
+
+type dummyCataloger struct {
+	name string
+}
+
+func (d dummyCataloger) Name() string { return d.name }
+func (d dummyCataloger) Catalog(_ context.Context, _ file.Resolver) ([]pkg.Package, []artifact.Relationship, error) {
+	return nil, nil, nil
+}
+
+func TestAllCatalogers(t *testing.T) {
+	t.Run("happy path", func(t *testing.T) {
+		catalogers, err := AllCatalogers()
+		require.NoError(t, err)
+		assert.Greater(t, len(catalogers), 10)
+
+		for i := 1; i < len(catalogers); i++ {
+			assert.LessOrEqual(t, catalogers[i-1].Name, catalogers[i].Name, "results should be sorted by name")
+		}
+
+		names := make(map[string]bool)
+		for _, c := range catalogers {
+			assert.NotEmpty(t, c.Name)
+			names[c.Name] = true
+		}
+
+		assert.True(t, names["python-installed-package-cataloger"], "should contain python-installed-package-cataloger")
+		assert.True(t, names["go-module-binary-cataloger"], "should contain go-module-binary-cataloger")
+	})
+
+	t.Run("contains file catalogers", func(t *testing.T) {
+		catalogers, err := AllCatalogers()
+		require.NoError(t, err)
+
+		hasFileCataloger := slices.ContainsFunc(catalogers, func(c Cataloger) bool {
+			return slices.Contains(c.Tags, "file")
+		})
+		assert.True(t, hasFileCataloger, "should include file catalogers")
+	})
+}
+
+func TestSelectCatalogers(t *testing.T) {
+	t.Run("with filter", func(t *testing.T) {
+		selection := cataloging.NewSelectionRequest().
+			WithDefaults("all").
+			WithSubSelections("python")
+
+		catalogers, err := SelectCatalogers(selection)
+		require.NoError(t, err)
+		assert.Greater(t, len(catalogers), 0)
+
+		for _, c := range catalogers {
+			// file catalogers are always included by the selection logic; skip them
+			if slices.Contains(c.Tags, "file") {
+				continue
+			}
+			assert.True(t, slices.Contains(c.Tags, "python"), "cataloger %q should have python tag", c.Name)
+		}
+	})
+
+	t.Run("empty selection", func(t *testing.T) {
+		catalogers, err := SelectCatalogers(cataloging.SelectionRequest{})
+		require.NoError(t, err)
+		assert.Empty(t, catalogers)
+	})
+
+	t.Run("with additional always-enabled cataloger", func(t *testing.T) {
+		ref := pkgcataloging.CatalogerReference{
+			Cataloger:     dummyCataloger{name: "my-custom-cataloger"},
+			AlwaysEnabled: true,
+			Tags:          []string{"custom"},
+		}
+
+		catalogers, err := SelectCatalogers(
+			cataloging.NewSelectionRequest().WithDefaults("all"),
+			ref,
+		)
+		require.NoError(t, err)
+
+		found := slices.ContainsFunc(catalogers, func(c Cataloger) bool {
+			return c.Name == "my-custom-cataloger"
+		})
+		assert.True(t, found, "should include the always-enabled custom cataloger")
+	})
+
+	t.Run("with additional selectable cataloger matching selection", func(t *testing.T) {
+		ref := pkgcataloging.CatalogerReference{
+			Cataloger: dummyCataloger{name: "my-python-cataloger"},
+			Tags:      []string{"python", "custom"},
+		}
+
+		catalogers, err := SelectCatalogers(
+			cataloging.NewSelectionRequest().WithDefaults("all").WithSubSelections("custom"),
+			ref,
+		)
+		require.NoError(t, err)
+
+		found := slices.ContainsFunc(catalogers, func(c Cataloger) bool {
+			return c.Name == "my-python-cataloger"
+		})
+		assert.True(t, found, "should include custom cataloger that matches selection")
+	})
+
+	t.Run("with additional selectable cataloger not matching selection", func(t *testing.T) {
+		ref := pkgcataloging.CatalogerReference{
+			Cataloger: dummyCataloger{name: "my-ruby-cataloger"},
+			Tags:      []string{"ruby", "custom"},
+		}
+
+		catalogers, err := SelectCatalogers(
+			cataloging.NewSelectionRequest().WithDefaults("all").WithSubSelections("python"),
+			ref,
+		)
+		require.NoError(t, err)
+
+		found := slices.ContainsFunc(catalogers, func(c Cataloger) bool {
+			return c.Name == "my-ruby-cataloger"
+		})
+		assert.False(t, found, "should not include custom cataloger that does not match selection")
+	})
+
+	t.Run("always-enabled cataloger included even with empty selection", func(t *testing.T) {
+		ref := pkgcataloging.CatalogerReference{
+			Cataloger:     dummyCataloger{name: "my-persistent-cataloger"},
+			AlwaysEnabled: true,
+			Tags:          []string{"custom"},
+		}
+
+		catalogers, err := SelectCatalogers(cataloging.SelectionRequest{}, ref)
+		require.NoError(t, err)
+
+		require.Len(t, catalogers, 1)
+		assert.Equal(t, "my-persistent-cataloger", catalogers[0].Name)
+	})
+}

syft/exp/doc.go

@@ -0,0 +1,9 @@
+// Package exp provides experimental APIs for the syft library.
+//
+// APIs in this package have NO stability guarantees. They may change or be
+// removed in any release without notice. Do not depend on their behavior
+// in production systems.
+//
+// Once an API has proven stable and useful, it may be promoted to the main
+// syft package with proper stability guarantees.
+package exp