Improve struct and field comments and incorporate into json schema (#4252)

* improve struct and field comments and incorporate into json schema

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

* address review feedback

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

---------

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

syft/file/coordinate_set.go

@@ -7,6 +7,7 @@ import (
 	"github.com/scylladb/go-set/strset"
 )
 
+// CoordinateSet provides a unique collection of Coordinates with set operations.
 type CoordinateSet struct {
 	set map[Coordinates]struct{}
 }

syft/file/coordinates.go

@@ -9,8 +9,11 @@ import (
 
 // Coordinates contains the minimal information needed to describe how to find a file within any possible source object (e.g. image and directory sources)
 type Coordinates struct {
-	RealPath     string `json:"path" cyclonedx:"path"`                 // The path where all path ancestors have no hardlinks / symlinks
-	FileSystemID string `json:"layerID,omitempty" cyclonedx:"layerID"` // An ID representing the filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank.
+	// RealPath is the canonical absolute form of the path accessed (all symbolic links have been followed and relative path components like '.' and '..' have been removed).
+	RealPath string `json:"path" cyclonedx:"path"`
+
+	// FileSystemID is an ID representing and entire filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank.
+	FileSystemID string `json:"layerID,omitempty" cyclonedx:"layerID"`
 }
 
 func NewCoordinates(realPath, fsID string) Coordinates {

syft/file/digest.go

@@ -1,6 +1,10 @@
 package file
 
+// Digest represents a cryptographic hash of file contents.
 type Digest struct {
+	// Algorithm specifies the hash algorithm used (e.g., "sha256", "md5").
 	Algorithm string `json:"algorithm"`
-	Value     string `json:"value"`
+
+	// Value is the hexadecimal string representation of the hash.
+	Value string `json:"value"`
 }

syft/file/executable.go

@@ -1,40 +1,60 @@
 package file
 
 type (
-	ExecutableFormat   string
+	// ExecutableFormat represents the binary executable format type.
+	ExecutableFormat string
+
+	// RelocationReadOnly indicates the RELRO security protection level applied to an ELF binary.
 	RelocationReadOnly string
 )
 
 const (
-	ELF   ExecutableFormat = "elf"
-	MachO ExecutableFormat = "macho"
-	PE    ExecutableFormat = "pe"
+	ELF   ExecutableFormat = "elf"   // Executable and Linkable Format used on Unix-like systems
+	MachO ExecutableFormat = "macho" // Mach object file format used on macOS and iOS
+	PE    ExecutableFormat = "pe"    // Portable Executable format used on Windows
 
-	RelocationReadOnlyNone    RelocationReadOnly = "none"
-	RelocationReadOnlyPartial RelocationReadOnly = "partial"
-	RelocationReadOnlyFull    RelocationReadOnly = "full"
+	RelocationReadOnlyNone    RelocationReadOnly = "none"    // no RELRO protection
+	RelocationReadOnlyPartial RelocationReadOnly = "partial" // partial RELRO protection
+	RelocationReadOnlyFull    RelocationReadOnly = "full"    // full RELRO protection
 )
 
+// Executable contains metadata about binary files and their security features.
 type Executable struct {
 	// Format denotes either ELF, Mach-O, or PE
 	Format ExecutableFormat `json:"format" yaml:"format" mapstructure:"format"`
 
-	HasExports          bool                 `json:"hasExports" yaml:"hasExports" mapstructure:"hasExports"`
-	HasEntrypoint       bool                 `json:"hasEntrypoint" yaml:"hasEntrypoint" mapstructure:"hasEntrypoint"`
-	ImportedLibraries   []string             `json:"importedLibraries" yaml:"importedLibraries" mapstructure:"importedLibraries"`
+	// HasExports indicates whether the binary exports symbols.
+	HasExports bool `json:"hasExports" yaml:"hasExports" mapstructure:"hasExports"`
+
+	// HasEntrypoint indicates whether the binary has an entry point function.
+	HasEntrypoint bool `json:"hasEntrypoint" yaml:"hasEntrypoint" mapstructure:"hasEntrypoint"`
+
+	// ImportedLibraries lists the shared libraries required by this executable.
+	ImportedLibraries []string `json:"importedLibraries" yaml:"importedLibraries" mapstructure:"importedLibraries"`
+
+	// ELFSecurityFeatures contains ELF-specific security hardening information when Format is ELF.
 	ELFSecurityFeatures *ELFSecurityFeatures `json:"elfSecurityFeatures,omitempty" yaml:"elfSecurityFeatures" mapstructure:"elfSecurityFeatures"`
 }
 
+// ELFSecurityFeatures captures security hardening and protection mechanisms in ELF binaries.
 type ELFSecurityFeatures struct {
+	// SymbolTableStripped indicates whether debugging symbols have been removed.
 	SymbolTableStripped bool `json:"symbolTableStripped" yaml:"symbolTableStripped" mapstructure:"symbolTableStripped"`
 
-	// classic protections
+	// StackCanary indicates whether stack smashing protection is enabled.
+	StackCanary *bool `json:"stackCanary,omitempty" yaml:"stackCanary" mapstructure:"stackCanary"`
 
-	StackCanary                   *bool              `json:"stackCanary,omitempty" yaml:"stackCanary" mapstructure:"stackCanary"`
-	NoExecutable                  bool               `json:"nx" yaml:"nx" mapstructure:"nx"`
-	RelocationReadOnly            RelocationReadOnly `json:"relRO" yaml:"relRO" mapstructure:"relRO"`
-	PositionIndependentExecutable bool               `json:"pie" yaml:"pie" mapstructure:"pie"`
-	DynamicSharedObject           bool               `json:"dso" yaml:"dso" mapstructure:"dso"`
+	// NoExecutable indicates whether NX (no-execute) protection is enabled for the stack.
+	NoExecutable bool `json:"nx" yaml:"nx" mapstructure:"nx"`
+
+	// RelocationReadOnly indicates the RELRO protection level.
+	RelocationReadOnly RelocationReadOnly `json:"relRO" yaml:"relRO" mapstructure:"relRO"`
+
+	// PositionIndependentExecutable indicates whether the binary is compiled as PIE.
+	PositionIndependentExecutable bool `json:"pie" yaml:"pie" mapstructure:"pie"`
+
+	// DynamicSharedObject indicates whether the binary is a shared library.
+	DynamicSharedObject bool `json:"dso" yaml:"dso" mapstructure:"dso"`
 
 	// LlvmSafeStack represents a compiler-based security mechanism that separates the stack into a safe stack for storing return addresses and other critical data, and an unsafe stack for everything else, to mitigate stack-based memory corruption errors
 	// see https://clang.llvm.org/docs/SafeStack.html

syft/file/license.go

@@ -5,18 +5,33 @@ import (
 	"github.com/anchore/syft/syft/license"
 )
 
+// License represents license information discovered within a file.
 type License struct {
-	Value           string
-	SPDXExpression  string
-	Type            license.Type
-	LicenseEvidence *LicenseEvidence // evidence from license classifier
-	Contents        string           `hash:"ignore"`
+	// Value is the raw license string as found in the file.
+	Value string
+
+	// SPDXExpression is the parsed SPDX license expression if available.
+	SPDXExpression string
+
+	// Type categorizes how the license was determined (e.g., declared, concluded -- following the same semantics as SPDX).
+	Type license.Type
+
+	LicenseEvidence *LicenseEvidence
+
+	// Contents optionally stores the full license text.
+	Contents string `hash:"ignore"`
 }
 
+// LicenseEvidence contains details from license classifier analysis.
 type LicenseEvidence struct {
+	// Confidence is a score indicating certainty of the license match.
 	Confidence int
-	Offset     int
-	Extent     int
+
+	// Offset is the byte position where the license text begins in the file.
+	Offset int
+
+	// Extent is the length in bytes of the matched license text.
+	Extent int
 }
 
 func NewLicense(value string) License {

syft/file/location.go

@@ -27,18 +27,24 @@ type Location struct {
 	LocationMetadata `cyclonedx:""`
 }
 
+// LocationData contains the core identifying information for a file location.
 type LocationData struct {
 	Coordinates `cyclonedx:""` // Empty string here means there is no intermediate property name, e.g. syft:locations:0:path without "coordinates"
 	// note: it is IMPORTANT to ignore anything but the coordinates for a Location when considering the ID (hash value)
 	// since the coordinates are the minimally correct ID for a location (symlinks should not come into play)
-	AccessPath string         `hash:"ignore" json:"accessPath"` // The path to the file which may or may not have hardlinks / symlinks
-	ref        file.Reference `hash:"ignore"`                   // The file reference relative to the stereoscope.FileCatalog that has more information about this location.
+
+	// AccessPath is the path used to retrieve file contents (which may or may not have hardlinks / symlinks in the path)
+	AccessPath string `hash:"ignore" json:"accessPath"`
+
+	// ref is the stereoscope file reference relative to the stereoscope.FileCatalog that has more information about this location.
+	ref file.Reference `hash:"ignore"`
 }
 
 func (l LocationData) Reference() file.Reference {
 	return l.ref
 }
 
+// LocationMetadata provides additional contextual information about a file location.
 type LocationMetadata struct {
 	Annotations map[string]string `json:"annotations,omitempty"` // Arbitrary key-value pairs that can be used to annotate a location
 }

syft/file/location_read_closer.go

@@ -2,6 +2,7 @@ package file
 
 import "io"
 
+// LocationReadCloser combines a Location with a ReadCloser for accessing file content with location metadata.
 type LocationReadCloser struct {
 	Location
 	io.ReadCloser

syft/file/location_set.go

@@ -9,6 +9,7 @@ import (
 	"github.com/anchore/syft/internal/log"
 )
 
+// LocationSet provides a unique collection of Locations with metadata and set operations.
 type LocationSet struct {
 	set map[LocationData]LocationMetadata
 }

syft/file/locations.go

@@ -8,6 +8,7 @@ import (
 
 var locationSorterWithoutLayers = LocationSorter(nil)
 
+// Locations is a sortable slice of Location values.
 type Locations []Location
 
 func (l Locations) Len() int {

syft/file/resolver.go

@@ -18,6 +18,7 @@ type ContentResolver interface {
 	FileContentsByLocation(Location) (io.ReadCloser, error)
 }
 
+// MetadataResolver provides file metadata lookup by location.
 type MetadataResolver interface {
 	FileMetadataByLocation(Location) (Metadata, error)
 }
@@ -51,6 +52,7 @@ type PathResolver interface {
 	RelativeFileByPath(_ Location, path string) *Location
 }
 
+// LocationResolver provides iteration over all file locations in a source.
 type LocationResolver interface {
 	// AllLocations returns a channel of all file references from the underlying source.
 	// The implementation for this may vary, however, generally the following considerations should be made:
@@ -59,6 +61,7 @@ type LocationResolver interface {
 	AllLocations(ctx context.Context) <-chan Location
 }
 
+// WritableResolver extends Resolver with the ability to write file content.
 type WritableResolver interface {
 	Resolver
 

syft/file/search_result.go

@@ -4,13 +4,25 @@ import (
 	"fmt"
 )
 
+// SearchResult represents a match found during content scanning, such as secret detection.
 type SearchResult struct {
+	// Classification identifies the type or category of the matched content.
 	Classification string `json:"classification"`
-	LineNumber     int64  `json:"lineNumber"`
-	LineOffset     int64  `json:"lineOffset"`
-	SeekPosition   int64  `json:"seekPosition"`
-	Length         int64  `json:"length"`
-	Value          string `json:"value,omitempty"`
+
+	// LineNumber is the 1-indexed line number where the match was found.
+	LineNumber int64 `json:"lineNumber"`
+
+	// LineOffset is the character offset from the start of the line where the match begins.
+	LineOffset int64 `json:"lineOffset"`
+
+	// SeekPosition is the absolute byte offset from the start of the file.
+	SeekPosition int64 `json:"seekPosition"`
+
+	// Length is the size in bytes of the matched content.
+	Length int64 `json:"length"`
+
+	// Value optionally contains the actual matched content.
+	Value string `json:"value,omitempty"`
 }
 
 func (s SearchResult) String() string {

syft/file/selection.go

@@ -1,9 +1,10 @@
 package file
 
 const (
-	NoFilesSelection             Selection = "none"
-	FilesOwnedByPackageSelection Selection = "owned-by-package"
-	AllFilesSelection            Selection = "all"
+	NoFilesSelection             Selection = "none"             // no files are selected
+	FilesOwnedByPackageSelection Selection = "owned-by-package" // only files owned by packages are selected
+	AllFilesSelection            Selection = "all"              // all files are selected
 )
 
+// Selection defines which files should be included during cataloging operations.
 type Selection string