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>
2026-11-03 07:56:36 +01:00 · 2025-10-03 17:01:56 +00:00
parent b96d3d20af
commit a77d24e379
57 changed files with 4241 additions and 1676 deletions
@@ -23,22 +23,50 @@ var _ FileOwner = (*ApkDBEntry)(nil)
 // - https://git.alpinelinux.org/apk-tools/tree/src/package.c
 // - https://git.alpinelinux.org/apk-tools/tree/src/database.c
 type ApkDBEntry struct {
-	Package       string          `mapstructure:"P" json:"package"`
-	OriginPackage string          `mapstructure:"o" json:"originPackage" cyclonedx:"originPackage"`
-	Maintainer    string          `mapstructure:"m" json:"maintainer"`
-	Version       string          `mapstructure:"V" json:"version"`
-	Architecture  string          `mapstructure:"A" json:"architecture"`
-	URL           string          `mapstructure:"U" json:"url"`
-	Description   string          `mapstructure:"T" json:"description"`
-	Size          int             `mapstructure:"S" json:"size" cyclonedx:"size"`
-	InstalledSize int             `mapstructure:"I" json:"installedSize" cyclonedx:"installedSize"`
-	Dependencies  []string        `mapstructure:"D" json:"pullDependencies" cyclonedx:"pullDependencies"`
-	Provides      []string        `mapstructure:"p" json:"provides" cyclonedx:"provides"`
-	Checksum      string          `mapstructure:"C" json:"pullChecksum" cyclonedx:"pullChecksum"`
-	GitCommit     string          `mapstructure:"c" json:"gitCommitOfApkPort" cyclonedx:"gitCommitOfApkPort"`
-	Files         []ApkFileRecord `json:"files"`
+	// Package is the package name as found in the installed file
+	Package string `mapstructure:"P" json:"package"`
+
+	// OriginPackage is the original source package name this binary was built from (used to track which aport/source built this)
+	OriginPackage string `mapstructure:"o" json:"originPackage" cyclonedx:"originPackage"`
+
+	// Maintainer is the package maintainer name and email
+	Maintainer string `mapstructure:"m" json:"maintainer"`
+
+	// Version is the package version as found in the installed file
+	Version string `mapstructure:"V" json:"version"`
+
+	// Architecture is the target CPU architecture
+	Architecture string `mapstructure:"A" json:"architecture"`
+
+	// URL is the upstream project URL
+	URL string `mapstructure:"U" json:"url"`
+
+	// Description is a human-readable package description
+	Description string `mapstructure:"T" json:"description"`
+
+	// Size is the package archive size in bytes (.apk file size)
+	Size int `mapstructure:"S" json:"size" cyclonedx:"size"`
+
+	// InstalledSize is the total size of installed files in bytes
+	InstalledSize int `mapstructure:"I" json:"installedSize" cyclonedx:"installedSize"`
+
+	// Dependencies are the runtime dependencies required by this package
+	Dependencies []string `mapstructure:"D" json:"pullDependencies" cyclonedx:"pullDependencies"`
+
+	// Provides are virtual packages provided by this package (for capability-based dependencies)
+	Provides []string `mapstructure:"p" json:"provides" cyclonedx:"provides"`
+
+	// Checksum is the package content checksum for integrity verification
+	Checksum string `mapstructure:"C" json:"pullChecksum" cyclonedx:"pullChecksum"`
+
+	// GitCommit is the git commit hash of the APK port definition in Alpine's aports repository
+	GitCommit string `mapstructure:"c" json:"gitCommitOfApkPort" cyclonedx:"gitCommitOfApkPort"`
+
+	// Files are the files installed by this package
+	Files []ApkFileRecord `json:"files"`
 }

+// spaceDelimitedStringSlice is an internal helper type for unmarshaling space-delimited strings from JSON into a string slice.
 type spaceDelimitedStringSlice []string

 func (m *ApkDBEntry) UnmarshalJSON(data []byte) error {
@@ -95,11 +123,20 @@ func (a *spaceDelimitedStringSlice) UnmarshalJSON(data []byte) error {

 // ApkFileRecord represents a single file listing and metadata from a APK DB entry (which may have many of these file records).
 type ApkFileRecord struct {
-	Path        string       `json:"path"`
-	OwnerUID    string       `json:"ownerUid,omitempty"`
-	OwnerGID    string       `json:"ownerGid,omitempty"`
-	Permissions string       `json:"permissions,omitempty"`
-	Digest      *file.Digest `json:"digest,omitempty"`
+	// Path is the file path relative to the filesystem root
+	Path string `json:"path"`
+
+	// OwnerUID is the file owner user ID
+	OwnerUID string `json:"ownerUid,omitempty"`
+
+	// OwnerGID is the file owner group ID
+	OwnerGID string `json:"ownerGid,omitempty"`
+
+	// Permissions is the file permission mode string (e.g. "0755", "0644")
+	Permissions string `json:"permissions,omitempty"`
+
+	// Digest is the file content hash for integrity verification
+	Digest *file.Digest `json:"digest,omitempty"`
 }

 func (m ApkDBEntry) OwnedFiles() (result []string) {