pkgdb

type APK struct{}

type Deb struct{}

type Format string

type Meta struct {
	// Vendor and Distribution are the VENDOR and DISTRIBUTION tags, verbatim:
	// "Rocky Enterprise Software Foundation" / "Rocky Linux 9", "SUSE LLC" /
	// "SUSE Linux Enterprise 15". Either may be empty; some rebuilders set
	// neither, which is why --osv-ecosystem exists.
	Vendor       string `json:"vendor,omitempty"`
	Distribution string `json:"distribution,omitempty"`

	// ELF are the installed paths whose FILECLASS entry names an ELF object.
	//
	// rpm stores file(1)'s output for every file it packages, in the header,
	// which means "does this package ship any code at all" is answerable
	// without decompressing the cpio payload -- no xz, no zstd, no cpio.
	// That single fact is what makes a metadata-only scan able to produce a
	// real not_present verdict rather than only undetermined ones.
	ELF []string `json:"elf,omitempty"`

	// FilesKnown reports whether the file list behind ELF was actually read.
	//
	// A package that genuinely ships no code and a package nobody looked at
	// are indistinguishable by ELF alone -- both have len(ELF) == 0 -- and the
	// two call for opposite verdicts: one is "there is no code here", the
	// other is "nothing was learned". Only a reader with the header in front
	// of it can tell them apart, so only ReadFile sets this. Every other way a
	// Meta comes into being -- an SBOM component, a hand-built literal --
	// leaves it false and gets the cautious answer, which is the direction a
	// zero value has to fall in a tool whose worst failure is a clean report.
	FilesKnown bool `json:"files_known,omitempty"`

	// SourcePackage is true for a .src.rpm. Source packages install nothing and
	// are not what a distribution files advisories against, so callers skip
	// them rather than report a package that cannot be installed.
	SourcePackage bool `json:"source_package,omitempty"`
}

type Package struct {
	Format Format `json:"format"`
	Name   string `json:"name"`
	// Version is the version string to compare against OSV ranges. For rpm
	// this is the full EVR with the epoch always present ("0:1.43.0-5.el9_3"),
	// because that is how the Red Hat, Rocky and AlmaLinux records are
	// written. See rpmEVR.
	Version string `json:"version"`
	Arch    string `json:"arch,omitempty"`

	// Epoch is the rpm epoch, broken out so a consumer can reconstruct the
	// epoch-free version for the ecosystems whose records omit it (Azure
	// Linux). Zero and meaningless for deb and apk.
	Epoch int `json:"epoch,omitempty"`

	// Source is the source (dpkg "Source:", apk "o:", rpm SOURCERPM) package
	// this was built from, when the database records one and it differs from
	// Name.
	Source string `json:"source,omitempty"`
	// SourceVersion is the source version when dpkg records one explicitly,
	// which it only does when it differs from Version.
	SourceVersion string `json:"source_version,omitempty"`

	// Files are the tree-absolute paths the package installs, as the database
	// records them: directories included, nothing stat'ed.
	Files []string `json:"files,omitempty"`

	// DB is the tree-absolute path of the database this came from, for
	// evidence and error messages.
	DB string `json:"db,omitempty"`
}

type RPM struct{}

type Reader interface {
	// Format names the package manager this reader understands.
	Format() Format
	// Detect reports whether the tree carries this kind of database, and the
	// tree-absolute path of the one it found.
	Detect(fsys target.RootFS) (string, bool)
	// Read parses the database. A database that Detect found but Read cannot
	// parse is an error, never an empty slice.
	Read(fsys target.RootFS) ([]Package, error)
}

type Result struct {
	Format   Format    `json:"format"`
	DB       string    `json:"db"`
	Packages []Package `json:"packages"`
}