mod sbom

module sbom

Planned CycloneDX 1.5 SBOM from a stack lock (pre-install inventory).

Built with the official cyclonedx_bom crate (same models as cargo-cyclonedx / CycloneDX Rust Cargo). Documents are serialized as JSON 1.5 with serial numbers, tool metadata, lifecycle phase, and declared dependency edges — not a post-build compliance scan.

Functions

fn artifact_facts_for_lock(lock: &StackLock) -> HashMap<String, ArtifactFacts>

Read the easyconfigs a lock names, for the facts only they carry.

This is the one place the module touches the filesystem, and it earns it: a lock records which easyconfig was selected, and the checksums and source URLs that make the document verifiable live in that file rather than in the lock. A path that cannot be read or parsed contributes nothing rather than failing the document, since an SBOM missing one component’s hashes is worth more than no SBOM, and the count of what was read is reported to the caller.

fn build_dep_map_from_universe(lock: &StackLock, universe: &Universe) -> HashMap<String, Vec<String>>

Build dep map name -> build-time dependency names (builddependencies) from universe candidates matching the lock.

fn closure_edges_for_lock(lock: &StackLock, lock_file: &Path) -> HashMap<String, Vec<String>>

Runtime and build edges for every locked module, keyed by lock identity.

Each tuple is resolved with resolve_locked_dep, the same walk the SBOM uses, so a build list ordered on this map puts every dependency before the module that needs it and keeps two versions of one name. A bare tuple still contributes: the walk inherits the parent toolchain, so the list waits for the selected module rather than every package that shares the name. An unreadable recipe contributes no edges. lock_file is the path the lock was written to; relative recipe paths resolve the way lock_to_cyclonedx_from_recipes resolves them.

This is what stack solve uses for --build-list-out and --jenkins-build-list-out. dep_map_from_universe stays for a caller that already holds the universe and has not written the recipes.

fn dep_map_from_universe(lock: &StackLock, universe: &Universe) -> HashMap<String, Vec<String>>

Build dep map name -> runtime dependency names from universe candidates matching the lock. Build-time deps are intentionally omitted here so SBOM dependsOn edges stay role-specific; use build_dep_map_from_universe for the build-time list (same shape, separate map).

The solve path does not call this. Its build list reads closure_edges_for_lock from the recipes the lock names. This function stays for a caller that holds the universe in memory and has no recipe files to read, which is how the JSON fixture tests build a name map.

fn dep_maps_for_lock(lock: &StackLock) -> (HashMap<String, Vec<String>>, HashMap<String, Vec<String>>)

Runtime and build-time dependency maps read from the easyconfigs a lock names, keeping only dependencies that are themselves in the lock.

A lock records what was chosen, not why; the edges live in the recipes. A solve has them in memory, but an SBOM written later from the lock alone would otherwise carry no dependsOn at all. Unreadable paths contribute no edges, as in artifact_facts_for_lock.

fn host_build_environment() -> BTreeMap<String, String>

Build-environment metadata from the current host for SBOM/test qualification.

fn lock_to_bom(lock: &StackLock, runtime_dep_map: Option<&HashMap<String, Vec<String>>>, build_dep_map: Option<&HashMap<String, Vec<String>>>) -> Bom

Typed CycloneDX BOM (1.5 models) — preferred when callers want validation.

fn lock_to_bom_with_facts(lock: &StackLock, facts: SbomFacts<'_>) -> Bom

Build the BOM from a lock plus whatever else the caller knows.

Everything beyond the lock is optional, and what is absent is left absent rather than guessed: a component with no stated checksum carries no hashes, and a plan with nothing unresolved is the only one that claims complete.

fn lock_to_cyclonedx(lock: &StackLock) -> Value

Build a CycloneDX JSON document from a lock only (no dependency map).

Without declared edges each component gets an empty dependsOn list — never all-to-all co-stack edges (those create invalid cyclic BOMs).

fn lock_to_cyclonedx_from_recipes(lock: &StackLock, lock_file: &Path) -> (Value, SbomReadStats)

CycloneDX for a lock, reading edges and checksums from its easyconfigs.

lock_file is the path the lock was read from. Relative recipe paths resolve through resolve_lock_easyconfig. The host optarch, CPU model, and architecture are recorded on the formulation so a generic-optarch document is not mistaken for a native one.

fn lock_to_cyclonedx_with_deps(lock: &StackLock, selected_dep_map: Option<&HashMap<String, Vec<String>>>) -> Value

Preferred: when the selected candidates (or full universe selection map) are known, emit dependsOn from each package’s declared EasyBuild-style dependency list intersected with co-selected lock members. When selected_dep_map is None, each package’s dependsOn is empty (unknown), not all-to-all.

fn lock_to_cyclonedx_with_facts(lock: &StackLock, facts: SbomFacts<'_>) -> Value

JSON document from a lock plus caller-supplied facts.

fn lock_to_cyclonedx_with_runtime_and_build(lock: &StackLock, runtime_dep_map: Option<&HashMap<String, Vec<String>>>, build_dep_map: Option<&HashMap<String, Vec<String>>>) -> Value

Like lock_to_cyclonedx_with_deps, also records build-time edges as a component property (eb_stack:buildDependsOn) while runtime edges fill the CycloneDX dependencies graph.

fn resolve_lock_easyconfig(lock_dir: &Path, easyconfig_path: &str) -> PathBuf

Where a lock’s easyconfig_path is on disk.

An absolute path is used as written. A relative path is the file next to the lock when that file exists, and otherwise the path against the process directory. A solve run from the repository root still finds fixtures/... paths; a later stack sbom whose working directory is elsewhere still finds paths stored relative to the lock.

fn solved_dependency_dot(lock: &StackLock, lock_file: &Path) -> String

Graphviz DOT for the dependency DAG of a solved lock.

A node is name/version plus the toolchain, and the versionsuffix when the selected recipe has one. An edge points from a package to a dependency it selected. The label is the requirement as the solver read it, plus a versionsuffix or an explicit toolchain when the tuple carries one. A builddependency that is not also a runtime dependency is dashed.

Edges come from the easyconfigs the lock names, the same walk as closure_edges_for_lock. A dependency the lock did not select is left out. Node order is the lock’s package order made deterministic by name, version, versionsuffix, and toolchain.

fn write_solved_dependency_graph(lock: &StackLock, lock_file: &Path, out: &Path) -> Result<(), String>

Write the solved dependency DAG.

.svg and .png are rendered with the Graphviz dot program. Any other suffix, including .dot, is the DOT source.

Structs and Unions

struct ArtifactFacts

What an easyconfig states about the artifact one component builds from.

A lock records a selection, not an artifact. These are the fields that make the difference between an inventory and a document someone can verify: which bytes were expected, and where they were fetched from.

checksums: Vec<String>

Checksums the easyconfig states, in the order it states them. Only 64-character hex values are emitted as SHA-256; anything else is carried as a property rather than asserted as a hash of the wrong kind.

source_urls: Vec<String>

Source URLs the easyconfig downloads from.

patches: Vec<String>

Patch filenames applied on top of the source.

struct SbomFacts<'a>

Everything a caller can tell the SBOM builder beyond the lock itself.

Grouped into one struct so the builder keeps a single entry point as more of the spec is filled in, rather than growing another positional argument per field.

runtime_dep_map: Option<&'a HashMap<String, Vec<String>>>

Runtime edges, which become the dependencies graph. Keyed by lock identity. A map keyed by package name still works when that name occurs once in the lock.

build_dep_map: Option<&'a HashMap<String, Vec<String>>>

Build edges, kept as a property because CycloneDX dependencies does not distinguish build from runtime in 1.5. Same key as Self::runtime_dep_map.

artifacts: Option<&'a HashMap<String, ArtifactFacts>>

Per-package artifact facts. Keyed by lock identity, or by package name when the lock carries one version of that name.

unresolved: Option<&'a [String]>

Requirements the plan could not resolve. Their presence is what makes the document’s compositions say incomplete rather than complete.

input_hashes: Option<&'a HashMap<String, String>>

Input hash per package name, from crate::input_hash. Used as the uid of the task that builds it, which is what CycloneDX means by a unique identifier for a resource instance: two plans producing the same hash describe the same build.

build_environment: Option<&'a BTreeMap<String, String>>

The build environment the plan targets: optimisation flags, compute capabilities, the EasyBuild version. A build is reproducible only against a stated environment, since the same recipe compiled with different flags is a different binary, and an SBOM that omits it describes something nobody can reproduce (doi:10.1109/ms.2021.3073045).

struct SbomReadStats

How many recipes a lock SBOM could read.

recipes_read: usize

Easyconfigs that parsed.

recipes_unreadable: usize

Paths that were missing, empty, or not an easyconfig.

with_artifact_facts: usize

Parsed recipes that stated a checksum or a source URL.