@exodus/stasis 1.0.0-beta.0 → 1.0.0-beta.10

package/src/sbom.js

@@ -1,33 +1,23 @@
-import semver from './apis/npm/semver.cjs'
+import { compareVersions, valid } from '@preventive/upstream/semver.js'
 import pkg from '../package.json' with { type: 'json' }
 
-// `@exodus/stasis/sbom` — derive an SPDX 2.3 or CycloneDX 1.5 Software Bill of
-// Materials from already-parsed stasis artifacts (`Bundle`/`Lockfile`
-// instances). This module is deliberately free of file/transport concerns: it
-// never reads disk and never touches brotli (`node:zlib`), so it can run
-// wherever an artifact instance can be handed to it. The CLI glue that reads
-// `stasis.code.br`/`stasis.lock.json` off disk (and so pulls in brotli) lives
-// in `src/cmd/sbom.js`.
+// Derive an SPDX 2.3 or CycloneDX 1.5 SBOM from already-parsed stasis artifacts (`Bundle`/`Lockfile`).
+// Deliberately free of file/transport concerns (no disk, no brotli); the disk-reading CLI glue is src/cmd/sbom.js.
 
-// Identity stamped into every generated SBOM's tool/creator metadata. The tool
-// name is the published package name, per the command's spec.
+// Tool/creator identity stamped into every generated SBOM.
 const DEFAULT_TOOL = { name: '@exodus/stasis', version: pkg.version, vendor: 'Exodus Movement, Inc.' }
 
-// Per-call UUID/timestamp without importing node:crypto — Web Crypto is global
-// in modern Node, keeping this module dependency-light.
+// Web Crypto (global) instead of node:crypto, keeping this module dependency-light.
 const newUuid = () => globalThis.crypto.randomUUID()
 
-// purl `type`s we know how to mint. A dependency whose recorded ecosystem has
-// no registered purl type (`soldeer`) gets no purl — better than a fabricated
-// one — while npm/composer/cargo/github all map to official types.
+// purl types we can mint; an ecosystem with no registered type (`soldeer`) gets no purl rather than a fabricated one,
+// and so does a crate vendored from git or from a source not known (`cargo-git`, `cargo-unknown`): `pkg:cargo` names
+// crates.io's crate of that name, which it may not be.
 const PURL_TYPES = new Set(['npm', 'composer', 'cargo', 'github'])
 
-// Infer a whole artifact's ecosystem from its loader formats. Used for the
-// first-party/workspace buckets (which never carry the per-dependency
-// `ecosystem` field) and as the fallback for older artifacts that predate the
-// field entirely. PHP bundles tag files with the `php` format and map to
-// Composer; everything else (JS/TS, and the Solidity/Rust/Bash source bundles,
-// which all bucket by `package.json`) uses npm-style names.
+// Infer an artifact's ecosystem from its loader formats: PHP bundles map to Composer, everything
+// else to npm. Used for untagged (first-party) buckets and as the fallback for legacy artifacts
+// predating the per-dependency `ecosystem` field.
 function detectEcosystem(artifact) {
   const formats = artifact.formats
   if (formats && typeof formats.values === 'function') {
@@ -38,19 +28,17 @@ function detectEcosystem(artifact) {
   return 'npm'
 }
 
-// Legacy scope classification for artifacts predating the per-dependency
-// `ecosystem` field: the "." bucket and other non-`node_modules` dirs are
-// first-party, except in a Composer bundle where vendor packages live outside
-// `node_modules`.
+// Legacy scope classification (pre-`ecosystem` artifacts): non-`node_modules` dirs are first-party,
+// except in a Composer bundle where vendor packages live outside `node_modules`. `node_modules` is
+// a path segment, as stasis-core's hasNodeModulesSegment has it: `foo_node_modules/x` is first-party.
 function classifyScope(ecosystem, dir) {
   if (dir === '.') return 'workspace'
   if (ecosystem === 'composer') return 'dependency'
-  return dir.includes('node_modules') ? 'dependency' : 'workspace'
+  return dir.split('/').includes('node_modules') ? 'dependency' : 'workspace'
 }
 
-// Split a package name into its purl/CycloneDX namespace (group) and bare name.
-// npm scopes (`@scope/name`), Composer vendors and GitHub owners (`a/b`) all use
-// the segment before the first slash; cargo crates and bare names have none.
+// Split a package name into purl/CycloneDX namespace (group) + bare name: npm scopes, Composer
+// vendors and GitHub owners use the segment before the first slash; cargo and bare names have none.
 function splitName(ecosystem, name) {
   const namespaced = ecosystem === 'composer' || ecosystem === 'github' ||
     (ecosystem === 'npm' && name.startsWith('@'))
@@ -61,12 +49,11 @@ function splitName(ecosystem, name) {
   return { group: undefined, name }
 }
 
-// Build a Package URL (purl) — the cross-format component identifier SPDX and
-// CycloneDX both understand — for a package in a known ecosystem, or null when
-// the ecosystem has no purl type. Each path segment is percent-encoded (so an
-// npm scope's `@` becomes `%40`), while the `/` namespace separator and the
-// `@` before the version stay literal, per the purl spec. Composer and GitHub
-// names are case-insensitive, so they're lowercased as the spec requires.
+// Build a Package URL (purl) for a known ecosystem, or null when it has no purl type. Each path
+// segment is percent-encoded (npm scope's `@` -> `%40`) while the `/` namespace separator and the
+// `@` before the version stay literal; Composer and GitHub names are lowercased, per the purl spec.
+// The version qualifier is optional in the purl spec, so a versionless workspace package mints a
+// bare-name purl rather than a fabricated version.
 export function buildPurl(ecosystem, rawName, version) {
   if (!PURL_TYPES.has(ecosystem)) return null
   let { group, name } = splitName(ecosystem, rawName)
@@ -75,93 +62,97 @@ export function buildPurl(ecosystem, rawName, version) {
     name = name.toLowerCase()
   }
   const namespace = group ? `${encodeURIComponent(group)}/` : ''
-  return `pkg:${ecosystem}/${namespace}${encodeURIComponent(name)}@${encodeURIComponent(version)}`
+  const at = version == null ? '' : `@${encodeURIComponent(version)}`
+  return `pkg:${ecosystem}/${namespace}${encodeURIComponent(name)}${at}`
 }
 
 function compareComponents(a, b) {
   if (a.name !== b.name) return a.name < b.name ? -1 : 1
-  if (a.version !== b.version) {
-    if (semver.valid(a.version) && semver.valid(b.version)) return semver.compare(a.version, b.version)
-    return a.version < b.version ? -1 : 1
+  // A missing version sorts first, as '' (comparing raw undefined would be order-unstable).
+  const [av, bv] = [a.version ?? '', b.version ?? '']
+  if (av !== bv) {
+    if (valid(av) && valid(bv)) return compareVersions(av, bv)
+    return av < bv ? -1 : 1
   }
   return a.ecosystem < b.ecosystem ? -1 : a.ecosystem > b.ecosystem ? 1 : 0
 }
 
-// Collect the deduplicated, sorted set of packages recorded across one or more
-// already-parsed stasis artifacts (`Bundle`/`Lockfile` instances). Unlike
-// `stasis audit` (which inventories only installed dependencies to query the
-// registry), an SBOM is the *full* bill of materials, so first-party/workspace
-// packages are included too — tagged `scope: 'workspace'` vs. `'dependency'` so
-// the formatters can pick a primary component. Buckets without a name+version
-// (legacy v0 bundles record neither) are skipped: there is nothing to attest.
-//
-// Each dependency's `ecosystem` (npm/composer/cargo/github/soldeer) comes from
-// the per-bucket field newer artifacts record; older artifacts predate it, so
-// we fall back to inferring it from the file's loader formats and install path.
-// Dedup is by ecosystem+name+version; a package seen as first-party in any
-// artifact stays workspace regardless of argument order, so the output doesn't
-// depend on how the artifacts are listed.
+// Collect the deduplicated, sorted set of packages across parsed artifacts. Unlike `stasis audit`
+// (installed deps only), an SBOM is the *full* bill of materials, so workspace/first-party packages
+// are included too, tagged scope 'workspace' vs 'dependency'. Buckets without a name are skipped,
+// and so are DEPENDENCY buckets without a version (v0 partial metadata: unverifiable identity) --
+// but a workspace package may legitimately omit version (private/unpublished) and is kept, since
+// dropping it would silently lose the document's own first-party subject. Dedup is by
+// ecosystem+name+version; a package seen as workspace in any artifact stays workspace regardless
+// of argument order, so output doesn't depend on how artifacts are listed.
+// A dependency's `vendored` packages (those copied into it whose files a bundle carries) ride on its
+// component as `vendored`, sorted by `dir`: each its `name`, the `version` its package.json gives if
+// any, and a purl only beside one -- a vendored package.json without a version names no release, and
+// may not name a registry package at all (Next.js calls its React copy `react-builtin`).
 export function collectComponents(artifacts) {
   const seen = new Map()
   for (const artifact of artifacts) {
     const records = [...artifact.modules]
-    // The per-dependency `ecosystem` field cleanly separates deps (tagged) from
-    // first-party buckets (untagged). If no bucket carries it, the artifact
-    // predates the field and we use the format/path heuristic for everything.
+    // The per-dependency `ecosystem` field separates deps (tagged) from first-party buckets (untagged);
+    // if no bucket carries it, the artifact predates the field and we use the heuristic for everything.
     const tagged = records.some(([, m]) => m.ecosystem !== undefined)
     const fileEcosystem = detectEcosystem(artifact)
-    for (const [dir, { name, version, ecosystem }] of records) {
-      if (!name || !version) continue
+    for (const [dir, { name, version, ecosystem, vendored }] of records) {
+      if (!name) continue
       let scope, eco
       if (ecosystem !== undefined) {
         scope = 'dependency'
         eco = ecosystem
       } else if (tagged) {
-        // Untagged bucket in a modern artifact: first-party workspace code. Its
-        // purl ecosystem is inferred (npm, or composer for a PHP project).
+        // Untagged bucket in a modern artifact: first-party workspace code; ecosystem inferred.
         scope = 'workspace'
         eco = fileEcosystem
       } else {
         scope = classifyScope(fileEcosystem, dir)
         eco = fileEcosystem
       }
-      const key = `${eco} ${name} ${version}`
-      const existing = seen.get(key)
-      if (existing) {
-        if (scope === 'workspace') existing.scope = 'workspace'
-        continue
+      if (!version && scope !== 'workspace') continue
+      const key = `${eco} ${name} ${version ?? ''}`
+      let component = seen.get(key)
+      if (component) {
+        if (scope === 'workspace') component.scope = 'workspace'
+      } else {
+        seen.set(key, component = { name, version: version ?? undefined, scope, ecosystem: eco, purl: buildPurl(eco, name, version) })
+      }
+      // Across artifacts, the union by directory; the first to list one names its package.
+      for (const [sub, v] of Object.entries(vendored ?? {})) {
+        component.vendored ??= new Map()
+        if (component.vendored.has(sub)) continue
+        component.vendored.set(sub, { dir: sub, name: v.name, version: v.version, ecosystem: eco, purl: v.version === undefined ? null : buildPurl(eco, v.name, v.version) })
       }
-      seen.set(key, { name, version, scope, ecosystem: eco, purl: buildPurl(eco, name, version) })
     }
   }
+  for (const component of seen.values()) {
+    if (component.vendored) component.vendored = [...component.vendored.values()].toSorted((a, b) => (a.dir < b.dir ? -1 : 1))
+  }
   return [...seen.values()].toSorted(compareComponents)
 }
 
-// Pick the single component the SBOM is *about* (its primary/root). That is the
-// lone workspace package when there is exactly one; with zero or several
-// workspace roots (a node_modules-only artifact, or several inputs/monorepo
-// packages) the BOM has no single subject and every package is listed as a
-// plain component. `rest` is everything that is not the primary.
+// Pick the single component the SBOM is *about* (its primary/root): the lone workspace package when
+// there is exactly one; with zero or several workspace roots there's no single subject, so every
+// package is a plain component. `rest` is everything that is not the primary.
 function selectPrimary(components) {
   const workspace = components.filter((c) => c.scope === 'workspace')
   const primary = workspace.length === 1 ? workspace[0] : null
   return { primary, rest: primary ? components.filter((c) => c !== primary) : components }
 }
 
-// SBOM timestamps are RFC 3339 / ISO 8601 to whole seconds (SPDX's canonical
-// `YYYY-MM-DDThh:mm:ssZ`); drop the milliseconds Date.toISOString includes.
+// SBOM timestamps are RFC 3339 to whole seconds; drop the milliseconds Date.toISOString includes.
 const isoSeconds = (date) => date.toISOString().replace(/\.\d{3}Z$/u, 'Z')
 
-// A CycloneDX bom-ref must uniquely identify a component within the document;
-// the purl does when present, and ecosystem+name+version is unique by
-// construction (it is the dedup key) otherwise.
-const bomRef = (c) => c.purl ?? `${c.ecosystem}:${c.name}@${c.version}`
+// A CycloneDX bom-ref must uniquely identify a component; use the purl when present, else
+// ecosystem+name(+version) (unique by construction -- it's the dedup key).
+const bomRef = (c) => c.purl ?? `${c.ecosystem}:${c.name}${c.version == null ? '' : `@${c.version}`}`
 
-// Render an SPDX 2.3 document (as a plain object) for the collected components.
-// The document DESCRIBES its primary component and the primary DEPENDS_ON each
-// installed dependency (a flat graph — every package in a lockfile/bundle is a
-// transitive dependency of the root). With no single primary the document
-// DESCRIBES the workspace packages, or every package when there are none.
+// Render an SPDX 2.3 document. It DESCRIBES its primary component, which DEPENDS_ON each installed
+// dependency (flat graph). With no single primary, the document DESCRIBES the workspace packages,
+// or every package when there are none. A package vendored into a dependency is a package of its own,
+// after the rest, which that dependency CONTAINS, its directory there its `packageFileName`.
 export function toSpdx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid = newUuid() } = {}) {
   const { primary, rest } = selectPrimary(components)
   const ordered = primary ? [primary, ...rest] : components
@@ -170,7 +161,8 @@ export function toSpdx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid
   const packages = ordered.map((c) => ({
     SPDXID: ids.get(c),
     name: c.name,
-    versionInfo: c.version,
+    // SPDX versionInfo is optional; omit it for a versionless workspace package.
+    ...(c.version == null ? {} : { versionInfo: c.version }),
     downloadLocation: 'NOASSERTION',
     filesAnalyzed: false,
     ...(c.purl && {
@@ -178,6 +170,21 @@ export function toSpdx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid
     }),
     primaryPackagePurpose: c.scope === 'workspace' ? 'APPLICATION' : 'LIBRARY',
   }))
+  const vendored = ordered.flatMap((c) => (c.vendored ?? []).map((v, i) => ({ host: c, v, id: `${ids.get(c)}-Vendored-${i}` })))
+  for (const { v, id } of vendored) {
+    packages.push({
+      SPDXID: id,
+      name: v.name,
+      ...(v.version == null ? {} : { versionInfo: v.version }),
+      packageFileName: v.dir,
+      downloadLocation: 'NOASSERTION',
+      filesAnalyzed: false,
+      ...(v.purl && {
+        externalRefs: [{ referenceCategory: 'PACKAGE-MANAGER', referenceType: 'purl', referenceLocator: v.purl }],
+      }),
+      primaryPackagePurpose: 'LIBRARY',
+    })
+  }
 
   const relationships = []
   if (primary) {
@@ -193,8 +200,13 @@ export function toSpdx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid
       relationships.push({ spdxElementId: 'SPDXRef-DOCUMENT', relatedSpdxElement: ids.get(c), relationshipType: 'DESCRIBES' })
     }
   }
+  for (const { host, id } of vendored) {
+    relationships.push({ spdxElementId: ids.get(host), relatedSpdxElement: id, relationshipType: 'CONTAINS' })
+  }
 
-  const docName = primary ? `${primary.name}@${primary.version}` : 'stasis-sbom'
+  const docName = primary
+    ? (primary.version == null ? primary.name : `${primary.name}@${primary.version}`)
+    : 'stasis-sbom'
   return {
     spdxVersion: 'SPDX-2.3',
     dataLicense: 'CC0-1.0',
@@ -210,10 +222,10 @@ export function toSpdx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid
   }
 }
 
-// Render a CycloneDX 1.5 document (as a plain object) for the collected
-// components. The primary (workspace root) becomes `metadata.component`; the
-// rest are listed in `components`, with a flat `dependencies` edge from the
-// primary to each installed dependency.
+// Render a CycloneDX 1.5 document. The primary (workspace root) becomes metadata.component; the
+// rest go in `components`, with a flat `dependencies` edge from primary to each installed dependency.
+// A package vendored into a dependency is nested in that dependency's `components`, its directory
+// there the location of its one occurrence.
 export function toCyclonedx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid = newUuid() } = {}) {
   const { primary, rest } = selectPrimary(components)
   const toComponent = (c) => {
@@ -223,8 +235,24 @@ export function toCyclonedx(components, { tool = DEFAULT_TOOL, now = new Date(),
       'bom-ref': bomRef(c),
       ...(group && { group }),
       name,
-      version: c.version,
+      // CycloneDX 1.5 `version` is optional; omit it for a versionless workspace package.
+      ...(c.version == null ? {} : { version: c.version }),
       ...(c.purl && { purl: c.purl }),
+      ...(c.vendored && { components: c.vendored.map((v) => toVendoredComponent(c, v)) }),
+    }
+  }
+  // Its bom-ref the host's with the directory as a purl subpath: two copies of one package (Next.js
+  // has loader-utils2 and loader-utils3, both `loader-utils`) stay apart.
+  const toVendoredComponent = (host, v) => {
+    const { group, name } = splitName(v.ecosystem, v.name)
+    return {
+      type: 'library',
+      'bom-ref': `${bomRef(host)}#${v.dir}`,
+      ...(group && { group }),
+      name,
+      ...(v.version == null ? {} : { version: v.version }),
+      ...(v.purl && { purl: v.purl }),
+      evidence: { occurrences: [{ location: v.dir }] },
     }
   }
 
@@ -235,8 +263,7 @@ export function toCyclonedx(components, { tool = DEFAULT_TOOL, now = new Date(),
     version: 1,
     metadata: {
       timestamp: isoSeconds(now),
-      // CycloneDX 1.5 `tools.components` shape: the flat tools array is
-      // deprecated in 1.5 (removed in 1.6), and newer consumers read this form.
+      // CycloneDX 1.5 `tools.components` shape: the flat tools array is deprecated in 1.5 (removed in 1.6).
       tools: { components: [{ type: 'application', publisher: tool.vendor, name: tool.name, version: tool.version }] },
       ...(primary && { component: toComponent(primary) }),
     },
@@ -249,18 +276,14 @@ export function toCyclonedx(components, { tool = DEFAULT_TOOL, now = new Date(),
   return doc
 }
 
-// Dispatch to the requested format. `components` is the output of
-// `collectComponents`; `options` accepts `{ tool, now, uuid }` for custom
-// tool identity / deterministic output.
+// Dispatch to the requested format; options: { tool, now, uuid } for custom identity / deterministic output.
 export function generateSbom(format, components, options) {
   if (format === 'spdx') return toSpdx(components, options)
   if (format === 'cyclonedx') return toCyclonedx(components, options)
   throw new Error(`sbom: format must be spdx or cyclonedx, got ${format}`)
 }
 
-// Convenience one-shot: collect the components from already-parsed artifacts and
-// render them in `format`. Equivalent to
-// `generateSbom(format, collectComponents(artifacts), options)`.
+// Convenience one-shot: collectComponents then generateSbom.
 export function sbom(format, artifacts, options) {
   return generateSbom(format, collectComponents(artifacts), options)
 }