langdb

type FileReader interface {
	Reader
	// FileSuffixes are the file extensions that identify this format's
	// packages, lowercase and including the dot.
	FileSuffixes() []string
}

type Format string

type Maven struct{}

type NPM struct{}

type Package struct {
	Format Format `json:"format"`

	// Name is the package name *as OSV keys it*: the PEP 503 normalized
	// project name for PyPI, the manifest name verbatim (scope included) for
	// npm.
	Name string `json:"name"`

	// AltNames are other names worth querying OSV under -- for PyPI, the
	// un-normalized project name as the metadata spells it. Same reasoning as
	// pkgdb.Package.OSVNames: a name that matches nothing costs one entry in a
	// batch query, while missing the right one reports a vulnerable package as
	// clean.
	AltNames []string `json:"alt_names,omitempty"`

	Version string `json:"version,omitempty"`

	// ImportNames are the top-level names the code is imported by: "yaml" and
	// "_yaml" for PyYAML, and just the package name for npm.
	ImportNames []string `json:"import_names,omitempty"`

	// ImportNamesKnown reports whether ImportNames came from the
	// distribution's own metadata rather than being guessed from its project
	// name.
	//
	// It exists because the two failure directions are not symmetric. A guessed
	// import name that is wrong makes the distribution unreachable in the
	// import graph, and an unreachable distribution reads as
	// vulnerable_code_not_in_execute_path -- a false clean. A consumer must be
	// able to refuse that conclusion, so the provenance travels with the data.
	ImportNamesKnown bool `json:"import_names_known"`

	// Files are the tree-absolute paths the distribution installs.
	Files []string `json:"files,omitempty"`

	// FilesKnown reports whether Files came from the distribution's own
	// manifest (RECORD, installed-files.txt) rather than being reconstructed
	// by walking its directories.
	//
	// Same asymmetry as ImportNamesKnown: an empty file list means "this
	// distribution ships no code", which is a not_present conclusion. Only a
	// manifest can support it.
	FilesKnown bool `json:"files_known"`

	// Dir is the tree-absolute directory the distribution's metadata lives in:
	// the .dist-info/.egg-info directory, or the package directory under
	// node_modules. The import resolver needs it to know which nested
	// node_modules an instance sees.
	Dir string `json:"dir,omitempty"`

	// DB is the site-packages or node_modules directory this came from, for
	// evidence and error messages.
	DB string `json:"db,omitempty"`

	// Requires are the packages this one declares it may load, named the way
	// Name is. It bounds what a computed import inside this package could
	// reach, which is the only thing that makes a dynamic-import taint able to
	// block anything narrower than the whole image.
	//
	// Only the PyPI reader fills this in. npm's resolver reads dependencies
	// from package.json itself, because for npm a name is not enough: which
	// copy of "tar" a file sees depends on the directory it is required from,
	// and that is precisely what nested node_modules means. Python's sys.path
	// is a single global search order, so a name resolves the same everywhere
	// and can be indexed once.
	Requires []Requirement `json:"requires,omitempty"`

	// RequiresKnown reports whether Requires came from readable metadata.
	//
	// Same asymmetry as FilesKnown. An empty Requires means "this package
	// depends on nothing", which narrows a taint's scope to the package
	// itself; only metadata that was actually read can support that.
	RequiresKnown bool `json:"requires_known"`

	// CoordsKnown reports whether Name came from metadata the build wrote
	// rather than from the file name or the code's own layout.
	//
	// Only the Maven reader ever sets it false. A PyPI or npm name is read from
	// a manifest that the package manager requires; a jar frequently carries no
	// statement of its own groupId at all, and the name is then reconstructed
	// from the file name and the classes' package prefixes.
	//
	// Same asymmetry as the rest of this family, one level up. A guessed
	// coordinate is still worth querying OSV with -- a name that matches nothing
	// costs one entry in a batch. It may not support a negative conclusion:
	// asserting that an artifact does not contain some class, when the artifact
	// is only what this reader thinks the jar is, stacks a guess on a guess.
	CoordsKnown bool `json:"coords_known,omitempty"`
}

type PyPI struct{}

type Reader interface {
	// Format names the ecosystem this reader understands.
	Format() Format
	// DirNames are the directory base names that hold this format's installed
	// packages, so one tree walk can find the roots for every reader.
	DirNames() []string
	// Read parses every root. A root that exists and cannot be listed is an
	// error; an individual manifest that will not parse is reported through
	// Result.Unreadable.
	Read(fsys target.RootFS, roots []string) (Result, error)
}

type Requirement struct {
	Name string `json:"name"`

	// Conditional reports whether the declaration carries an environment
	// marker -- an extra, a Python version bound, a platform test.
	//
	// It exists to separate two very different kinds of absence. An
	// unconditional dependency that is not installed means the environment is
	// not what the metadata describes, and nothing about it can be trusted to
	// bound anything. A conditional one that is not installed is the marker
	// working as designed: an unselected extra is *expected* to be missing,
	// and treating that as an unknown would push nearly every Python image
	// into a global taint.
	Conditional bool `json:"conditional,omitempty"`
}

type Result struct {
	Format Format `json:"format"`

	// Roots are what the tree walk found for this format: the site-packages or
	// node_modules directories, or, for a format whose packages are files, the
	// archive paths themselves.
	Roots []string `json:"roots"`

	Packages []Package `json:"packages"`

	// Unreadable are manifests that were found and could not be parsed.
	//
	// Unlike pkgdb, this is not a fatal error. A dpkg status file is one file
	// describing every package, so failing to parse it means knowing nothing;
	// here each distribution carries its own manifest, and a node_modules tree
	// routinely contains deliberately malformed fixtures. It is never silent
	// either: a distribution whose manifest could not be read is one whose
	// absence must not be asserted, so the plugin turns this into a taint.
	Unreadable []string `json:"unreadable,omitempty"`

	// Unidentified are archives that opened cleanly and declare no coordinates
	// anywhere -- no META-INF/maven, no usable manifest, no conventional file
	// name.
	//
	// It is Unreadable's sibling for the Maven reader, and it exists because the
	// two are the same failure wearing different clothes: something is installed
	// here and this scan cannot say what. A plugin asked whether an artifact is
	// present must not answer no while one of these is on the disk.
	Unidentified []string `json:"unidentified,omitempty"`
}