sbom

type BuildOptions struct {
	DocumentName string
	// DocumentNS pins the SPDX documentNamespace. Empty mints one in Bomly's
	// form, "https://bomly.dev/spdx/<uuid>", sharing the serial's UUID.
	DocumentNS      string
	ToolName        string
	ToolNames       []string
	ToolVersion     string
	Created         time.Time
	RootComponentID string
	// SerialNumber pins the CycloneDX serialNumber, an urn:uuid. Empty mints
	// one sharing the namespace's UUID.
	SerialNumber string

	// ProjectRoot, when non-nil, lets the projection synthesize a primary
	// component for the scanned project when the graph has no single root.
	ProjectRoot *ProjectRoot

	Provenance Provenance

	// Lifecycle is the CycloneDX lifecycle phase the document describes
	// (for example "pre-build" for source scans, "post-build" for container
	// images). Empty omits lifecycle metadata.
	Lifecycle string

	// Aggregate is the CycloneDX composition completeness declaration
	// ("complete", "incomplete", ...). Empty omits the declaration; callers
	// must only claim "complete" when nothing filtered or degraded the graph.
	Aggregate string

	// RestatesSource is true only when the export is a faithful restatement
	// of its single source document: nothing filtered, enriched, or degraded
	// the graph between ingest and export. Only then does a conversion adopt
	// the source's identity, creation time, name and comment (ADR-0042). The
	// default, false, is the safe side: the document mints its own identity
	// and links the source. Ignored with zero or several sources, and
	// overridden when a natively resolved entry sits beside the document:
	// that graph is a merge whatever the caller says.
	RestatesSource bool

	// Registry, when non-nil, supplies matching-stage enrichment (licenses,
	// vulnerabilities, CPEs, digests, EOL) resolved by PURL and folded onto
	// each component during projection.
	Registry *model.PackageRegistry
}

type Component struct {
	ID   string
	Name string

	// Org is the package namespace -- an npm scope, a Go module host and
	// owner, a Maven group. It is the PURL's namespace segment, emitted as
	// CycloneDX `group`. SPDX 2.3 has no equivalent field, so there it is
	// carried only inside the PURL external reference.
	Org string

	Version string

	// Scopes is the full scope set, not a scalar. A package reachable from
	// both a runtime and a development root carries both, and exporting only
	// the merged precedence value lost that at the SBOM boundary -- which is
	// the whole of what PR #406's scope union bought.
	//
	// Both formats hold one scope per component, so each encoder projects
	// this onto its own scalar and writes the set beside it in a carrier the
	// decoder prefers: a `bomly:scopes` CycloneDX property, a `scope=` field
	// in the SPDX package comment. The projection, the carrier format, and
	// the reverse mapping are all the SDK's (ADR-0037): they are one rule,
	// and a second copy here is how the forward and reverse directions came
	// to disagree in the first place.
	//
	// A source document's own scalar rides beside the set in SourceScope, so
	// the derived set is never the only record of what the document said.
	Scopes []model.Scope

	// SourceScope is the scope word the source document used, in that
	// document's own vocabulary -- CycloneDX's "optional", say. It is a
	// preserved claim and never an input to filtering: Scopes is what the
	// pipeline reads, and the SDK derives it from this.
	//
	// ADR-0037 asks that the word be re-emitted verbatim unless Bomly's own
	// scope set changed, so "optional" and "excluded" do not collapse into
	// "required" across a round trip that asserted neither. Whether the word
	// still means what the set means is model.CycloneDXScopeForExport's
	// decision, not this package's -- the mapping that read the word in is
	// the only thing that can say whether it still describes the set, and a
	// second copy of it here is how the two directions came to disagree
	// before.
	//
	// Only CycloneDX has a scalar to hold it. SPDX 2.3 has no scope field at
	// all, so an SPDX export carries the set in its comment carrier and the
	// source word stops there.
	SourceScope string

	PURL           string
	Ecosystem      string
	PackageManager string
	Type           string
	Copyright      string
	Licenses       []License

	// Matching-stage enrichment (populated when BuildOptions.Registry is set).
	CPEs            []string
	Digests         []Digest
	Vulnerabilities []Vulnerability
	EOL             *EOL

	// Where the package came from. A detector asserts at most one of
	// ArtifactURL and VCSURL; registry enrichment may then fill VCSURL from a
	// resolved source repository when it is empty, so a component enriched
	// under --enrich can carry both. VCSRevision only accompanies VCSURL.
	// Both are plain absolute http(s) URLs; composing them into a format's
	// locator grammar is the encoder's job.
	ArtifactURL string
	VCSURL      string
	VCSRevision string

	// What the source document asserted about this component, beyond its
	// identity (ADR-0037, issue #396).
	//
	// These carry a foreign document's own claims through the graph so a
	// conversion does not silently drop them: `bomly scan --sbom --format
	// spdx` used to lose the supplier, description, checksums, CPEs and
	// references its input stated, because the only things surviving the
	// graph hop were coordinates, scope, copyright and licenses.
	//
	// They are SDK types rather than local structs on purpose. Each carries
	// its own publication gate -- Contact.Normalized, ExternalReference
	// .Normalized -- and every value crossing this boundary re-clears it,
	// because an ingested document is untrusted input that Bomly re-emits.
	// A local mirror of these shapes would be a second place for those rules
	// to be forgotten, which is the defect ADR-0037 replaced.
	Supplier    *model.Contact
	Originator  *model.Contact
	Description string
	Homepage    string

	// ExternalReferences are the document's own references, kept with the
	// category and type it stated so the SPDX triple round-trips without
	// being re-derived. Merge class: set, unioned by the reference's own
	// identity.
	ExternalReferences []model.ExternalReference

	// Every place this package was resolved from, primary first.
	//
	// ADR-0041 folds equal-identity records into one node and keeps their
	// disagreement as a list of origins -- a package resolved from two
	// different registries or mirrors is exactly the dependency-confusion
	// signal that fold exists to preserve. The single-valued fields above
	// carry the first, because a format has one download location; this
	// carries all of them, so the evidence survives the export boundary
	// rather than stopping at it.
	Origins []ComponentOrigin
}

type ComponentOrigin struct {
	ArtifactURL string
	Repository  string
	Revision    string
}

type Dependency struct {
	Ref       string
	DependsOn []string
}

type Digest struct {
	Algorithm string
	Value     string
}

type Document struct {
	Name         string
	Namespace    string
	Tool         string
	Tools        []string
	ToolVersion  string
	Created      time.Time
	SerialNumber string
	// SerialVersion is the CycloneDX document revision that goes with
	// SerialNumber. A serial names a BOM; the revision names which issue of
	// it, so adopting a source's serial without its revision produced a
	// document claiming to be revision 1 of a BOM whose revision 2 it had
	// actually converted. Zero means unset and encodes as 1.
	SerialVersion int
	Provenance    Provenance
	Lifecycle     string
	Aggregate     string

	Components   []Component
	Dependencies []Dependency
	Roots        []string

	// Described are the components the document names as its subject, as
	// decoded: CycloneDX metadata.component, the targets of SPDX DESCRIBES
	// and DESCRIBED_BY. Roots are the graph's entry points and can include a
	// component the document never called its subject -- a disconnected
	// package, say -- so the two are kept apart. Empty for a document
	// projected from a graph, whose subject is its single root.
	Described []string

	// Assertions are the claims this document makes about itself: its
	// identity, name, data license, creators, tools, and comment. A decoder
	// fills them; ingest carries them onto the graph entry the document
	// became, so a later export can say what the source said (ADR-0037).
	//
	// This is what a document says about *itself*, which is why it is not the
	// same field as Sources below.
	Assertions model.DocumentAssertions

	// UnknownScopeTokens are the scope-carrier tokens an ingested document
	// named that this build does not recognize, deduplicated and sorted.
	//
	// The carrier is Bomly's own, so an unreadable token is most likely one a
	// newer Bomly wrote. The scopes beside it are still kept -- that is the
	// point of the SDK's lenient read -- but the fact that something was not
	// read is worth telling a user, and this package has no logger of its
	// own. The SBOM detector is where it becomes a warning.
	//
	// Empty for a document Bomly wrote and for a document with no carrier at
	// all.
	UnknownScopeTokens []string

	// Sources are the documents this one was built from, one per ingested
	// SBOM, in entry order.
	//
	// Empty for a native scan: nothing was ingested, so Bomly's own document
	// asserts everything itself. One source is the conversion case, where the
	// document restates that source's assertions -- the fixed point issue
	// #396 requires. Two or more is the merge case, where the document
	// asserts its own aggregate identity and *links* each source rather than
	// inheriting one, because both formats give a document exactly one
	// identity and picking a source's would name a document that is not this
	// one.
	Sources []model.DocumentAssertions
}

type EOL struct {
	EOL           bool
	EOLDate       string
	Cycle         string
	LatestVersion string
}

type EncodeOptions struct {
	Pretty bool
}

type License struct {
	Value          string
	SPDXExpression string
	Type           string
}

type ProjectRoot struct {
	Name    string
	Version string
}

type Provenance struct {
	Manufacturer               string
	SecurityContact            string
	VulnerabilityDisclosureURL string
	SupportEnd                 string
}

type Target string

type Vulnerability struct {
	ID            string
	Source        string
	Severity      string
	Score         *float64
	Vector        string
	Method        string
	CWEs          []int
	FixedVersions []string
	Advisories    []string
	Description   string

	// Recommendation is remediation guidance derived from known fixed
	// versions (CycloneDX `recommendation`; SPDX 2.3 has no equivalent).
	Recommendation string

	// Analysis is the VEX impact analysis the source attached to this
	// advisory for this component (CycloneDX `analysis`; SPDX 2.3 has no
	// equivalent). The SDK type is used directly, as the other assertions
	// are (ADR-0037): a projection would have to be re-gated on both sides.
	Analysis *model.VulnerabilityAnalysis
}