add docs to configs (#4281)

Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com>

.gitignore

@@ -16,6 +16,8 @@ bin/
 /snapshot
 /.tool
 /.task
+/generate
+/specs
 
 # changelog generation
 CHANGELOG.md

internal/packagemetadata/generate/main.go

@@ -5,8 +5,9 @@ import (
 	"os"
 	"strings"
 
-	"github.com/anchore/syft/internal/packagemetadata"
 	"github.com/dave/jennifer/jen"
+
+	"github.com/anchore/syft/internal/packagemetadata"
 )
 
 // This program is invoked from syft/internal and generates packagemetadata/generated.go

internal/sourcemetadata/generate/main.go

@@ -4,8 +4,9 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/dave/jennifer/jen"
+
+	"github.com/anchore/syft/internal/sourcemetadata"
 )
 
 // This program is invoked from syft/internal and generates sourcemetadata/generated.go

syft/format/common/spdxhelpers/to_format_model_test.go

@@ -7,7 +7,6 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/spdx/tools-golang/spdx"
@@ -16,6 +15,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/anchore/syft/internal/relationship"
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/artifact"
 	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/format/internal/spdxutil/helpers"

syft/format/github/internal/model/model_test.go

@@ -3,12 +3,12 @@ package model
 import (
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/stretchr/testify/assert"
 
 	"github.com/anchore/packageurl-go"
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/linux"
 	"github.com/anchore/syft/syft/pkg"

syft/format/internal/cyclonedxutil/helpers/component.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 
 	"github.com/CycloneDX/cyclonedx-go"
-	"github.com/anchore/syft/internal/packagemetadata"
 
 	"github.com/anchore/packageurl-go"
+	"github.com/anchore/syft/internal/packagemetadata"
 	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/format/internal"
 	"github.com/anchore/syft/syft/pkg"

syft/format/internal/spdxutil/helpers/document_name_test.go

@@ -5,9 +5,9 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/stretchr/testify/assert"
 
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/source"
 )
 

syft/format/internal/spdxutil/helpers/document_namespace_test.go

@@ -5,9 +5,9 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/stretchr/testify/assert"
 
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/sbom"
 	"github.com/anchore/syft/syft/source"
 )

syft/format/internal/spdxutil/helpers/originator_supplier_test.go

@@ -3,9 +3,9 @@ package helpers
 import (
 	"testing"
 
-	"github.com/anchore/syft/internal/packagemetadata"
 	"github.com/stretchr/testify/assert"
 
+	"github.com/anchore/syft/internal/packagemetadata"
 	"github.com/anchore/syft/syft/pkg"
 )
 

syft/format/syftjson/model/source_test.go

@@ -4,11 +4,11 @@ import (
 	"encoding/json"
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/google/go-cmp/cmp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/source"
 )

syft/format/syftjson/schema_test.go

@@ -6,9 +6,10 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/anchore/syft/internal/packagemetadata"
 	"github.com/iancoleman/strcase"
 	"github.com/stretchr/testify/require"
+
+	"github.com/anchore/syft/internal/packagemetadata"
 )
 
 type schema struct {

syft/format/syftjson/to_format_model_test.go

@@ -4,13 +4,13 @@ import (
 	"encoding/json"
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	stereoscopeFile "github.com/anchore/stereoscope/pkg/file"
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/format/syftjson/model"
 	"github.com/anchore/syft/syft/pkg"

syft/format/syftjson/to_syft_model_test.go

@@ -7,11 +7,11 @@ import (
 	"os"
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	stereoFile "github.com/anchore/stereoscope/pkg/file"
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/artifact"
 	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/format/syftjson/model"

syft/get_source_test.go

@@ -3,10 +3,10 @@ package syft
 import (
 	"testing"
 
-	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/stretchr/testify/require"
 
 	"github.com/anchore/stereoscope/pkg/image"
+	"github.com/anchore/syft/internal/sourcemetadata"
 	"github.com/anchore/syft/syft/source"
 	"github.com/anchore/syft/syft/source/sourceproviders"
 )

syft/pkg/cataloger/bitnami/package.go

@@ -7,7 +7,7 @@ import (
 	"slices"
 	"strings"
 
-	version "github.com/bitnami/go-version/pkg/version"
+	"github.com/bitnami/go-version/pkg/version"
 
 	"github.com/anchore/packageurl-go"
 	"github.com/anchore/syft/syft/artifact"

syft/pkg/cataloger/dotnet/config.go

@@ -2,17 +2,21 @@ package dotnet
 
 type CatalogerConfig struct {
 	// DepPackagesMustHaveDLL allows for deps.json packages to be included only if there is a DLL on disk for that package.
+	// app-config: dotnet.dep-packages-must-have-dll
 	DepPackagesMustHaveDLL bool `mapstructure:"dep-packages-must-have-dll" json:"dep-packages-must-have-dll" yaml:"dep-packages-must-have-dll"`
 
 	// DepPackagesMustClaimDLL allows for deps.json packages to be included only if there is a runtime/resource DLL claimed in the deps.json targets section.
 	// This does not require such claimed DLLs to exist on disk. The behavior of this
+	// app-config: dotnet.dep-packages-must-claim-dll
 	DepPackagesMustClaimDLL bool `mapstructure:"dep-packages-must-claim-dll" json:"dep-packages-must-claim-dll" yaml:"dep-packages-must-claim-dll"`
 
 	// PropagateDLLClaimsToParents allows for deps.json packages to be included if any child (transitive) package claims a DLL. This applies to both the claims configuration and evidence-on-disk configurations.
+	// app-config: dotnet.propagate-dll-claims-to-parents
 	PropagateDLLClaimsToParents bool `mapstructure:"propagate-dll-claims-to-parents" json:"propagate-dll-claims-to-parents" yaml:"propagate-dll-claims-to-parents"`
 
 	// RelaxDLLClaimsWhenBundlingDetected will look for indications of IL bundle tooling via deps.json package names
 	// and, if found (and this config option is enabled), will relax the DepPackagesMustClaimDLL value to `false` only in those cases.
+	// app-config: dotnet.relax-dll-claims-when-bundling-detected
 	RelaxDLLClaimsWhenBundlingDetected bool `mapstructure:"relax-dll-claims-when-bundling-detected" json:"relax-dll-claims-when-bundling-detected" yaml:"relax-dll-claims-when-bundling-detected"`
 }
 

syft/pkg/cataloger/golang/config.go

@@ -19,19 +19,48 @@ var (
 )
 
 type CatalogerConfig struct {
+	// SearchLocalModCacheLicenses enables searching for go package licenses in the local GOPATH mod cache.
+	// app-config: golang.search-local-mod-cache-licenses
 	SearchLocalModCacheLicenses bool `yaml:"search-local-mod-cache-licenses" json:"search-local-mod-cache-licenses" mapstructure:"search-local-mod-cache-licenses"`
+
+	// LocalModCacheDir specifies the location of the local go module cache directory. When not set, syft will attempt to discover the GOPATH env or default to $HOME/go.
+	// app-config: golang.local-mod-cache-dir
 	LocalModCacheDir string `yaml:"local-mod-cache-dir" json:"local-mod-cache-dir" mapstructure:"local-mod-cache-dir"`
+
+	// SearchLocalVendorLicenses enables searching for go package licenses in the local vendor directory relative to the go.mod file.
+	// app-config: golang.search-local-vendor-licenses
 	SearchLocalVendorLicenses bool `yaml:"search-local-vendor-licenses" json:"search-local-vendor-licenses" mapstructure:"search-local-vendor-licenses"`
+
+	// LocalVendorDir specifies the location of the local vendor directory. When not set, syft will search for a vendor directory relative to the go.mod file.
+	// app-config: golang.local-vendor-dir
 	LocalVendorDir string `yaml:"local-vendor-dir" json:"local-vendor-dir" mapstructure:"local-vendor-dir"`
+
+	// SearchRemoteLicenses enables downloading go package licenses from the upstream go proxy (typically proxy.golang.org).
+	// app-config: golang.search-remote-licenses
 	SearchRemoteLicenses bool `yaml:"search-remote-licenses" json:"search-remote-licenses" mapstructure:"search-remote-licenses"`
+
+	// Proxies is a list of go module proxies to use when fetching go module metadata and licenses. When not set, syft will use the GOPROXY env or default to https://proxy.golang.org,direct.
+	// app-config: golang.proxy
 	Proxies []string `yaml:"proxies,omitempty" json:"proxies,omitempty" mapstructure:"proxies"`
+
+	// NoProxy is a list of glob patterns that match go module names that should not be fetched from the go proxy. When not set, syft will use the GOPRIVATE and GONOPROXY env vars.
+	// app-config: golang.no-proxy
 	NoProxy []string `yaml:"no-proxy,omitempty" json:"no-proxy,omitempty" mapstructure:"no-proxy"`
+
 	MainModuleVersion MainModuleVersionConfig `yaml:"main-module-version" json:"main-module-version" mapstructure:"main-module-version"`
 }
 
 type MainModuleVersionConfig struct {
+	// FromLDFlags enables parsing the main module version from the -ldflags build settings.
+	// app-config: golang.main-module-version.from-ld-flags
 	FromLDFlags bool `yaml:"from-ld-flags" json:"from-ld-flags" mapstructure:"from-ld-flags"`
+
+	// FromContents enables parsing the main module version from the binary contents. This is useful when the version is embedded in the binary but not in the build settings.
+	// app-config: golang.main-module-version.from-contents
 	FromContents bool `yaml:"from-contents" json:"from-contents" mapstructure:"from-contents"`
+
+	// FromBuildSettings enables parsing the main module version from the go build settings.
+	// app-config: golang.main-module-version.from-build-settings
 	FromBuildSettings bool `yaml:"from-build-settings" json:"from-build-settings" mapstructure:"from-build-settings"`
 }
 

syft/pkg/cataloger/internal/pkgtest/test_generic_parser.go

@@ -336,6 +336,9 @@ func (p *CatalogTester) assertPkgs(t *testing.T, pkgs []pkg.Package, relationshi
 		opts = append(opts, p.compareOptions...)
 		opts = append(opts, cmp.Reporter(&r))
 
+		// ignore the "FoundBy" field on relationships as it is set in the generic cataloger before it's presence on the relationship
+		opts = append(opts, cmpopts.IgnoreFields(pkg.Package{}, "FoundBy"))
+
 		// order should not matter
 		relationship.Sort(p.expectedRelationships)
 		relationship.Sort(relationships)

syft/pkg/cataloger/java/cataloger.go

@@ -41,11 +41,14 @@ func NewPomCataloger(cfg ArchiveCatalogerConfig) pkg.Cataloger {
 // Note: Older versions of lockfiles aren't supported yet
 func NewGradleLockfileCataloger() pkg.Cataloger {
 	return generic.NewCataloger("java-gradle-lockfile-cataloger").
-		WithParserByGlobs(parseGradleLockfile, gradleLockfileGlob)
+		WithParserByGlobs(parseGradleLockfile, "**/gradle.lockfile*")
 }
 
 // NewJvmDistributionCataloger returns packages representing JDK/JRE installations (of multiple distribution types).
 func NewJvmDistributionCataloger() pkg.Cataloger {
 	return generic.NewCataloger("java-jvm-cataloger").
-		WithParserByGlobs(parseJVMRelease, jvmReleaseGlob)
+		// this is a very permissive glob that will match more than just the JVM release file.
+		// we started with "**/{java,jvm}/*/release", but this prevents scanning JVM archive contents (e.g. jdk8u402.zip).
+		// this approach lets us check more files for JVM release info, but be rather silent about errors.
+		WithParserByGlobs(parseJVMRelease, "**/release")
 }

syft/pkg/cataloger/java/config.go

@@ -9,11 +9,29 @@ import (
 
 type ArchiveCatalogerConfig struct {
 	cataloging.ArchiveSearchConfig `yaml:",inline" json:"" mapstructure:",squash"`
+
+	// 	UseNetwork enables network operations for java package metadata enrichment, such as fetching parent POMs and license information.
+	// app-config: java.use-network
 	UseNetwork bool `yaml:"use-network" json:"use-network" mapstructure:"use-network"`
+
+	// UseMavenLocalRepository enables searching the local maven repository (~/.m2/repository by default) for parent POMs and other metadata.
+	// app-config: java.use-maven-local-repository
 	UseMavenLocalRepository bool `yaml:"use-maven-localrepository" json:"use-maven-localrepository" mapstructure:"use-maven-localrepository"`
+
+	// MavenLocalRepositoryDir specifies the location of the local maven repository. When not set, defaults to ~/.m2/repository.
+	// app-config: java.maven-local-repository-dir
 	MavenLocalRepositoryDir string `yaml:"maven-localrepository-dir" json:"maven-localrepository-dir" mapstructure:"maven-localrepository-dir"`
+
+	// MavenBaseURL specifies the base URL(s) to use for fetching POMs and metadata from maven central or other repositories. When not set, defaults to https://repo1.maven.org/maven2.
+	// app-config: java.maven-url
 	MavenBaseURL string `yaml:"maven-base-url" json:"maven-base-url" mapstructure:"maven-base-url"`
+
+	// MaxParentRecursiveDepth limits how many parent POMs will be fetched recursively before stopping. This prevents infinite loops or excessively deep parent chains.
+	// app-config: java.max-parent-recursive-depth
 	MaxParentRecursiveDepth int `yaml:"max-parent-recursive-depth" json:"max-parent-recursive-depth" mapstructure:"max-parent-recursive-depth"`
+
+	// ResolveTransitiveDependencies enables resolving transitive dependencies for java packages found within archives.
+	// app-config: java.resolve-transitive-dependencies
 	ResolveTransitiveDependencies bool `yaml:"resolve-transitive-dependencies" json:"resolve-transitive-dependencies" mapstructure:"resolve-transitive-dependencies"`
 }
 

syft/pkg/cataloger/java/parse_gradle_lockfile.go

@@ -11,8 +11,6 @@ import (
 	"github.com/anchore/syft/syft/pkg/cataloger/generic"
 )
 
-const gradleLockfileGlob = "**/gradle.lockfile*"
-
 // lockfileDependency represents a single dependency in the gradle.lockfile file
 type lockfileDependency struct {
 	Group   string

syft/pkg/cataloger/java/parse_jvm_release.go

@@ -22,10 +22,6 @@ import (
 )
 
 const (
-	// this is a very permissive glob that will match more than just the JVM release file.
-	// we started with "**/{java,jvm}/*/release", but this prevents scanning JVM archive contents (e.g. jdk8u402.zip).
-	// this approach lets us check more files for JVM release info, but be rather silent about errors.
-	jvmReleaseGlob = "**/release"
 	oracleVendor   = "oracle"
 	openJdkProduct = "openjdk"
 	jre            = "jre"

syft/pkg/cataloger/javascript/config.go

@@ -3,8 +3,14 @@ package javascript
 const npmBaseURL = "https://registry.npmjs.org"
 
 type CatalogerConfig struct {
+	// SearchRemoteLicenses enables querying the NPM registry API to retrieve license information for packages that are missing license data in their local metadata.
+	// app-config: javascript.search-remote-licenses
 	SearchRemoteLicenses bool `json:"search-remote-licenses" yaml:"search-remote-licenses" mapstructure:"search-remote-licenses"`
+	// NPMBaseURL specifies the base URL for the NPM registry API used when searching for remote license information.
+	// app-config: javascript.npm-base-url
 	NPMBaseURL string `json:"npm-base-url" yaml:"npm-base-url" mapstructure:"npm-base-url"`
+	// IncludeDevDependencies controls whether development dependencies should be included in the catalog results, in addition to production dependencies.
+	// app-config: javascript.include-dev-dependencies
 	IncludeDevDependencies bool `json:"include-dev-dependencies" yaml:"include-dev-dependencies" mapstructure:"include-dev-dependencies"`
 }
 

syft/pkg/cataloger/kernel/cataloger.go

@@ -17,6 +17,8 @@ import (
 var _ pkg.Cataloger = (*linuxKernelCataloger)(nil)
 
 type LinuxKernelCatalogerConfig struct {
+	// CatalogModules enables cataloging linux kernel modules (*.ko files) in addition to the kernel itself.
+	// app-config: linux-kernel.catalog-modules
 	CatalogModules bool `yaml:"catalog-modules" json:"catalog-modules" mapstructure:"catalog-modules"`
 }
 

syft/pkg/cataloger/nix/cataloger.go

@@ -10,6 +10,8 @@ import (
 )
 
 type Config struct {
+	// CaptureOwnedFiles determines whether to record the list of files owned by each Nix package discovered in the store. Recording owned files provides more detailed information but increases processing time and memory usage.
+	// app-config: nix.capture-owned-files
 	CaptureOwnedFiles bool `json:"capture-owned-files" yaml:"capture-owned-files" mapstructure:"capture-owned-files"`
 }
 

syft/pkg/cataloger/python/cataloger.go

@@ -11,6 +11,8 @@ import (
 const eggInfoGlob = "**/*.egg-info"
 
 type CatalogerConfig struct {
+	// GuessUnpinnedRequirements attempts to infer package versions from version constraints when no explicit version is specified in requirements files.
+	// app-config: python.guess-unpinned-requirements
 	GuessUnpinnedRequirements bool `yaml:"guess-unpinned-requirements" json:"guess-unpinned-requirements" mapstructure:"guess-unpinned-requirements"`
 }
 

syft/pkg/cataloger/rust/cataloger.go

@@ -9,8 +9,6 @@ import (
 	"github.com/anchore/syft/syft/pkg/cataloger/generic"
 )
 
-const cargoAuditBinaryCatalogerName = "cargo-auditable-binary-cataloger"
-
 // NewCargoLockCataloger returns a new Rust Cargo lock file cataloger object.
 func NewCargoLockCataloger() pkg.Cataloger {
 	return generic.NewCataloger("rust-cargo-lock-cataloger").
@@ -20,6 +18,6 @@ func NewCargoLockCataloger() pkg.Cataloger {
 // NewAuditBinaryCataloger returns a new Rust auditable binary cataloger object that can detect dependencies
 // in binaries produced with https://github.com/Shnatsel/rust-audit
 func NewAuditBinaryCataloger() pkg.Cataloger {
-	return generic.NewCataloger(cargoAuditBinaryCatalogerName).
+	return generic.NewCataloger("cargo-auditable-binary-cataloger").
 		WithParserByMimeTypes(parseAuditBinary, mimetype.ExecutableMIMETypeSet.List()...)
 }

syft/pkg/cataloger/rust/package.go

@@ -33,7 +33,6 @@ func newPackageFromAudit(dep *rustaudit.Package, locations ...file.Location) pkg
 		Language:  pkg.Rust,
 		Type:      pkg.RustPkg,
 		Locations: file.NewLocationSet(locations...),
-		FoundBy:   cargoAuditBinaryCatalogerName,
 		Metadata: pkg.RustBinaryAuditEntry{
 			Name:    dep.Name,
 			Version: dep.Version,