@exodus/stasis 1.0.0-beta.1 → 1.0.0-beta.3

package/src/mock.js

@@ -1,52 +1,33 @@
-// Imported by src/loader-mock.js (the `stasis run --mock` entry) after the
-// @exodus/stasis-core hooks lib is evaluated but before its hooks are installed.
-// The goal is to capture the import graph for a bundle by actually running user
-// code, but with outbound side-effects denied. Pair with Node's `--permission`
-// flag (see bin/stasis.js when run with `--mock`), which fail-closed-denies fs
-// writes, child processes, worker threads, native addons, and the inspector at
-// the runtime boundary. This file covers what `--permission` cannot: there is no
-// `--allow-net`, so the network builtins are neutralized here in JS.
+// Imported by src/loader-mock.js (the `stasis run --mock` entry) after the core hooks lib is
+// evaluated but before its hooks are installed. Captures the import graph by running user code
+// with side-effects denied. Pairs with Node's `--permission` (see bin/stasis.js), which denies fs
+// writes/child procs/workers/addons/inspector at the runtime boundary; this file covers what
+// `--permission` can't -- there is no `--allow-net`, so the network builtins are neutralized in JS.
 //
-// Design: FAIL CLOSED, WHOLE MODULE.
-//  - We replace *every* callable on each network builtin with a thrower, not a
-//    curated method list. There is no "I forgot net.Socket#connect" gap: if
-//    it's a function on a denied module (factory, constructor, or helper),
-//    invoking it is denied. This also closes higher-level HTTP clients
-//    (axios/got/node-fetch/undici/ws) for free -- they all bottom out at
-//    node:net / node:tls / node:dns.
-//  - Anything we don't explicitly model still fails closed, because the call
-//    throws rather than silently succeeding.
+// FAIL CLOSED, WHOLE MODULE: replace *every* callable on a denied builtin with a thrower, not a
+// curated method list -- higher-level clients (axios/undici/ws) fall closed too since they bottom
+// out at node:net/tls/dns, and anything unmodelled still throws rather than silently succeeding.
 //
-// Mechanism: node:test's MockTracker can only redefine *configurable*
-// properties. ESM namespace objects (`import * as net from 'node:net'`) freeze
-// their bindings, so mocking the ESM namespace throws "Cannot redefine
-// property". The CommonJS exports object for the same builtin is mutable, and
-// ESM live-bindings track CJS mutation for builtins -- so we go through
-// `createRequire` to grab the mutable object and let live bindings propagate to
-// any importer that loads *after* us. Modules linked before this file runs keep
-// their original bindings -- which is exactly why the loader's own state.js
-// (node:fs/path/url/module/zlib/buffer, none of them network) keeps working.
+// Mechanism: go through `createRequire` to grab the *mutable* CJS exports object -- ESM namespace
+// objects freeze their bindings, so mocking them throws "Cannot redefine property". ESM live-bindings
+// track CJS mutation for builtins, so importers loading *after* us see the mocks; modules linked
+// before (the loader's own state.js) keep their real bindings.
 
 import { mock } from 'node:test'
 import { createRequire, syncBuiltinESMExports } from 'node:module'
 
 const require = createRequire(import.meta.url)
 
-// Force lazy initialization of process.stdin/stdout/stderr *before* we mock
-// the net/tls constructors. Node's process.std{in,out,err} are lazy getters
-// that construct an underlying net.Socket (or tty.WriteStream) on first read;
-// syncBuiltinESMExports() below would otherwise trigger those getters as it
-// materializes node:process's ESM wrapper, and the constructor would hit our
-// mock and throw mid-setup. Reading the property once here caches the real
-// Socket/TTY in Node's closure, so the later sync just reads the cached value.
+// Force lazy init of process.std{in,out,err} before mocking net/tls: they're lazy getters that
+// build a net.Socket/tty.WriteStream on first read, which syncBuiltinESMExports() below would
+// otherwise trigger through our mock mid-setup. Reading once here caches the real Socket/TTY.
 void process.stdin
 void process.stdout
 void process.stderr
 
 const MARKER = '[stasis --mock]'
 
-// Tagged so the unhandledRejection trap below can tell our denials apart from
-// genuine application bugs.
+// Tagged (__stasisMock) so the unhandledRejection trap below can tell our denials from real bugs.
 const blocked = (label) => {
   const err = new Error(`${MARKER} ${label} is blocked while capturing imports`)
   err.code = 'ERR_STASIS_MOCK_BLOCKED'
@@ -54,29 +35,18 @@ const blocked = (label) => {
   return err
 }
 
-// A *regular* (constructable) function, so that both `mod.factory()` and
-// `new mod.Constructor()` throw our attributable error -- an arrow function
-// would make `new` fail with a confusing "is not a constructor" TypeError.
+// A *regular* (constructable) function so both `mod.factory()` and `new mod.Constructor()` throw
+// our error; an arrow would make `new` fail with a confusing "is not a constructor".
 const denyFn = (label) => function () { throw blocked(label) }
 
-// Promise-shaped version: returns a rejected promise instead of sync-throwing.
-// Used for node:fs/promises, node:dns/promises, and similar. Fire-and-forget
-// `void fsPromises.writeFile(...)` then surfaces as an unhandledRejection
-// (caught by the trap below) rather than crashing the script synchronously.
+// Promise-shaped version: rejects instead of sync-throwing, so fire-and-forget callers surface via
+// the unhandledRejection trap below rather than crashing the script synchronously.
 const denyFnAsync = (label) => function () { return Promise.reject(blocked(label)) }
 
-// Replace every own function on `mod` (and, one level down, on `mod.promises`)
-// with a thrower. The factory picks denyFnAsync for promise-shaped surfaces
-// (/promises submodules) so fire-and-forget callers reject quietly through
-// the unhandledRejection trap below rather than crashing the script with a
-// synchronous throw -- *except* for class-shaped exports (PascalCase),
-// because `new Class()` on a function that returns a Promise yields the
-// Promise as the constructed value (per the `new` semantics), and the caller
-// then sees a confused `r.resolve is not a function` instead of our
-// attributable error. Sync-throw classes give the clean error in both
-// `new dnsp.Resolver()` and `dns.lookup()` cases. Functions are configurable
-// on the builtins we target; fall back to direct assignment on the off
-// chance one isn't.
+// Replace every own function on `mod` (and one level down on `mod.promises`) with a thrower.
+// Promise-shaped surfaces use denyFnAsync so fire-and-forget callers reject quietly -- except
+// class-shaped exports (PascalCase): `new Class()` returning a Promise yields the Promise as the
+// constructed value, so classes sync-throw to give a clean error in both `new` and call form.
 const isClassName = (key) => /^[A-Z]/.test(key)
 const denyModuleSurface = (specifier, mod, opts = {}) => {
   const { prefix = specifier, async: isAsync = specifier.endsWith('/promises') } = opts
@@ -96,29 +66,14 @@ const denyModuleSurface = (specifier, mod, opts = {}) => {
   }
 }
 
-// Every callable on these builtins is replaced with a thrower. The list
-// covers two categories:
-//
-//   1) Network surface (http/https/http2/net/dgram/tls/dns) -- the permission
-//      system has no --allow-net counterpart, so JS-mock is the *only* layer.
-//
-//   2) Process / worker surface (child_process/worker_threads/cluster/
-//      inspector) -- already denied at the kernel level by --permission (no
-//      --allow-child-process / --allow-worker / --allow-inspector and no
-//      --allow-addons). We duplicate the deny here on purpose: a JS-level
-//      thrower surfaces a clean, attributable ERR_STASIS_MOCK_BLOCKED instead
-//      of the kernel's ERR_ACCESS_DENIED, and it's defense in depth against
-//      anything that might quietly slip the permission rule (a future
-//      bypass, a misconfigured --allow flag, code that grabs primitives via
-//      process.binding before --permission's check fires, ...).
+// Every callable on these builtins is replaced with a thrower.
 const DENY_ALL = [
   // Network surface (no --allow-net counterpart -- JS-mock is the only layer).
   'node:http', 'node:https', 'node:http2',
   'node:net', 'node:dgram', 'node:tls',
   'node:dns', 'node:dns/promises',
-  // Process / worker / debug. Already kernel-denied by --permission; we
-  // duplicate the deny here for attributable errors and defense in depth
-  // against a future --allow-* slip-up or a process.binding bypass.
+  // Process/worker/debug: already --permission-denied; duplicated for attributable errors and
+  // defense in depth against a future --allow-* slip-up or a process.binding bypass.
   'node:child_process',
   'node:worker_threads',
   'node:cluster',
@@ -128,15 +83,9 @@ const DENY_ALL = [
   'node:repl',         // repl.start() opens an interactive stdin loop
   'node:sqlite',       // DatabaseSync can open/create SQLite files (Node 22+)
   'node:trace_events', // createTracing() can write trace files
-  'node:v8',           // writeHeapSnapshot bypasses node:fs (goes through V8);
-                       // setFlagsFromString mutates global V8 state. Serialize/
-                       // deserialize are blocked too -- if a package needs them
-                       // it can't run under --mock, which is consistent with
-                       // the "deny whole module" stance.
-  // node:wasi is *not* in this list: just require('node:wasi') emits an
-  // ExperimentalWarning to stderr on every --mock run, and --permission
-  // without --allow-wasi already denies WASI construction at the kernel
-  // level. The duplicate-deny isn't worth the warning noise.
+  'node:v8',           // writeHeapSnapshot bypasses node:fs; setFlagsFromString mutates global V8 state
+  // node:wasi is deliberately omitted: require('node:wasi') emits an ExperimentalWarning, and
+  // --permission already denies WASI construction at the kernel level.
 ]
 
 for (const specifier of DENY_ALL) {
@@ -149,24 +98,10 @@ for (const specifier of DENY_ALL) {
   denyModuleSurface(specifier, mod)
 }
 
-// process method denials. process.exit / process.abort are deliberately left
-// alone -- if user code wants to terminate early, let it; that's not a side
-// effect we should hide. The rest mutate global process state, do real I/O,
-// or talk to a parent over IPC:
-//   - chdir affects fs resolution for everything that runs after
-//   - kill signals other processes
-//   - umask affects every future file create
-//   - dlopen loads a native addon (--permission also denies)
-//   - binding returns Node's internal C++ bindings (--permission also denies);
-//     we duplicate to match the "process.binding bypass" claim in the header
-//   - setUid/setGid/setEuid/setEgid/setgroups/initgroups change privileges
-//     (--permission also denies these). Duplicated for attributable errors
-//   - send / disconnect talk to the parent over IPC (when the process was
-//     forked with stdio:'ipc'); not blocked by --permission
-//   - setSourceMapsEnabled / loadEnvFile mutate global Node state and (in
-//     loadEnvFile's case) read+mutate process.env from a file
-//   - setUncaughtExceptionCaptureCallback replaces Node's exception
-//     handling, which would also disable our exitCode=13 cleanup
+// process method denials. process.exit / process.abort are deliberately left alone -- early
+// termination isn't a side effect we should hide. The rest mutate global process state, do real
+// I/O, or talk to a parent over IPC; note setUncaughtExceptionCaptureCallback would also disable
+// our exitCode=13 cleanup below.
 const PROCESS_DENY = [
   'chdir', 'kill', 'umask', 'dlopen', 'binding',
   'setUid', 'setGid', 'setEuid', 'setEgid', 'setgroups', 'initgroups',
@@ -180,24 +115,14 @@ for (const name of PROCESS_DENY) {
   }
 }
 
-// process.report.writeReport(filename) writes a diagnostic JSON file to disk
-// (under --report-dir or cwd by default). Deny it so user code can't drop
-// reports into the project tree. process.report is an object, present on all
-// Node 12+ builds; the methods inside it are configurable.
+// process.report.writeReport writes a diagnostic JSON file to disk; deny it too.
 if (process.report && typeof process.report.writeReport === 'function') {
   mock.method(process.report, 'writeReport', denyFn('process.report.writeReport()'))
 }
 
-// fs writers: --permission blocks them at the kernel level too, but we mock
-// at the JS layer for cleaner attributable errors and so that user code can't
-// even *try* to mutate files inside the project's cwd (which is on the
-// --allow-fs-write list so stasis can emit its bundle/lockfile). Reads stay
-// real so node_modules resolution and config discovery keep working. This
-// works because loader-mock.js evaluates the core hooks lib *before* importing
-// us, so stasis's own destructured `import { writeFileSync } from 'node:fs'`
-// snapshots are already taken and it keeps real fs; the syncBuiltinESMExports()
-// call below then refreshes the node:fs ESM wrapper so the user's subsequent
-// ESM imports see the mocked names.
+// fs writers: --permission blocks these at the kernel level too, but JS-mocking gives cleaner
+// errors and stops user code mutating even cwd files (cwd is on --allow-fs-write for the bundle).
+// Reads stay real so node_modules resolution keeps working.
 const fs = require('node:fs')
 const fsPromises = require('node:fs/promises')
 const FS_WRITERS = [
@@ -221,25 +146,14 @@ for (const name of FS_WRITERS) {
   }
 }
 
-// Refresh the node:fs / node:fs/promises ESM wrappers so destructured/
-// namespace ESM imports made *after* this point see the mocked names.
-// Bindings already captured by stasis's own modules (linked before this file
-// ran) keep their snapshot of the real functions.
+// Refresh the node:fs ESM wrappers so ESM imports after this point see the mocked names;
+// bindings stasis already captured (linked before this file ran) keep their real snapshot.
 syncBuiltinESMExports()
 
-// Global fetch / WebSocket / EventSource come from undici, not node:http, so
-// they need separate handling. (Their transport bottoms out at node:net, which
-// is already blocked above -- but intercepting here yields a clean, attributable
-// error instead of a confusing low-level socket failure.) These globals are
-// writable + configurable, so assign directly.
-//
-// fetch returns a *forever-pending* promise rather than rejecting -- same
-// "silently ignored" semantics as the promise-style timers. An awaiter hangs,
-// fire-and-forget `void fetch(url)` quietly sits as a pending promise, and we
-// don't need an unhandledRejection trap (no rejection is produced). The event
-// loop is unaffected by a pending promise on its own, so the capture still
-// drains and the bundle gets written on beforeExit. WebSocket/EventSource
-// throw from their constructors so the synchronous shape is preserved.
+// Global fetch / WebSocket / EventSource come from undici, not node:http, so handle separately.
+// fetch returns a *forever-pending* promise (not a rejection) so an awaiter hangs and the capture
+// still drains to write the bundle on beforeExit; WebSocket/EventSource throw from their
+// constructors to preserve the synchronous shape.
 if (typeof globalThis.fetch === 'function') {
   globalThis.fetch = () => new Promise(() => {})
 }
@@ -251,42 +165,23 @@ for (const name of ['WebSocket', 'EventSource']) {
   }
 }
 
-// Our promise-shaped mocks (fs/promises, dns/promises, ...) sync-throw, which
-// `await` converts into a rejection. A fire-and-forget caller (no .catch / no
-// try-catch) would otherwise surface as unhandledRejection and tear the
-// process down before the loader writes the bundle on beforeExit. Swallow
-// *only* our own denials; rethrow everything else so real bugs still crash.
+// Our denials become unhandledRejections for fire-and-forget callers, which would tear the process
+// down before the loader writes the bundle. Swallow *only* our own denials; rethrow everything else.
 process.on('unhandledRejection', (reason) => {
   if (reason?.__stasisMock) return
   throw reason
 })
 
-// User code that awaits a denied promise (a forever-pending timer, an
-// undelivered fetch) leaves the top-level await unsettled, which Node 24+
-// flags by setting exitCode=13 at exit time. The bundle has already been
-// written by then (state.write() ran at beforeExit, before this), so the
-// capture itself succeeded -- override the 13 back to 0 so the CLI doesn't
-// report failure. Anything other than 13 (real assertion failure, syntax
-// error, ...) is preserved.
+// Node 24+ sets exitCode=13 when a top-level await stays unsettled (e.g. an awaited denied
+// promise). The bundle already wrote at beforeExit, so reset 13 -> 0; any other code is preserved.
 process.on('exit', () => {
   if (process.exitCode === 13) process.exitCode = 0
 })
 
-// Timers: silently ignored. Callback-style timers (setTimeout/setInterval/
-// setImmediate) become no-ops -- the callback never runs and the scheduling
-// call returns normally so user code keeps going. Promise-style timers
-// (node:timers/promises) return *forever-pending* promises: `await
-// setTimeout(...)` suspends forever and any code past the await never runs.
-// That's the "silently ignored" semantics for promise timers -- the awaiter
-// is dropped, not given a synthetic value. The process still exits cleanly
-// because a pending promise on its own doesn't keep the event loop alive, so
-// once everything else drains, Node tears down (logging an unsettled-
-// top-level-await warning) and the loader's beforeExit hook writes the
-// bundle.
-//
-// Stasis itself does not import node:timers anywhere, so unlike node:fs the
-// ESM wrapper for node:timers/timers-promises is not pre-materialized; the
-// CJS exports mutation below propagates to the user's first ESM import.
+// Timers: silently ignored. Callback timers (setTimeout/setInterval/setImmediate) become no-ops;
+// promise timers (node:timers/promises) return *forever-pending* promises so `await setTimeout()`
+// suspends forever. A pending promise doesn't keep the event loop alive, so the process still
+// exits cleanly and the loader's beforeExit hook writes the bundle.
 const noop = () => undefined
 const pending = () => new Promise(() => {})
 for (const name of ['setTimeout', 'setInterval', 'setImmediate']) globalThis[name] = noop
@@ -300,9 +195,8 @@ for (const name of ['setTimeout', 'setInterval', 'setImmediate', 'clearTimeout',
 const timersPromises = require('node:timers/promises')
 mock.method(timersPromises, 'setTimeout', pending)
 mock.method(timersPromises, 'setImmediate', pending)
-// setInterval returns an async iterable; each `await iter.next()` is also a
-// forever-pending promise, so `for await (const _ of setInterval(...))` hangs
-// at the first iteration -- the loop body never runs.
+// setInterval returns an async iterable; each `await iter.next()` is forever-pending, so
+// `for await (const _ of setInterval(...))` hangs at the first iteration.
 mock.method(timersPromises, 'setInterval', () => ({
   [Symbol.asyncIterator]() {
     return { next: pending }

package/src/parse.js

@@ -4,18 +4,9 @@ import { brotliDecompressSync } from 'node:zlib'
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { Lockfile } from '@exodus/stasis-core/lockfile'
 
-// Read a stasis artifact from disk and parse it into a Lockfile or Bundle,
-// reporting which kind it turned out to be. `kind` is one of:
-//   'lockfile' -- a `stasis.lock.json` (files recorded as SRI digests)
-//   'bundle'   -- a `stasis.code.br` (one unified format holding both code and
-//                 resources; per-file encoding is read from its `formats` map)
-// The bundle is one format: code files hash as UTF-8 text and 'resource:base64'
-// files hash as their decoded bytes, decided per-file by `stasis diff` from the
-// bundle's formats rather than from a whole-bundle kind.
-//
-// Lockfiles are JSON text starting with `{`; bundles are brotli-compressed JSON.
-// Sniff the leading byte to route to the right parser so its diagnostic surfaces
-// on failure.
+// Read a stasis artifact and parse it into a Lockfile or Bundle, reporting its `kind`
+// ('lockfile' | 'bundle'). Lockfiles are JSON starting with `{`; bundles are brotli-compressed
+// JSON — sniff the leading byte to route to the right parser so its diagnostic surfaces on failure.
 export function parseFileWithKind(file) {
   let buf
   try {
@@ -44,10 +35,7 @@ export function parseFileWithKind(file) {
   }
 }
 
-// Read a stasis artifact from disk and parse it into a Lockfile or Bundle.
-// Shared by `stasis audit` and `stasis sbom`, which both inventory the packages
-// a lockfile/bundle records and don't care which kind it is. Thin wrapper over
-// `parseFileWithKind` that drops the `kind`.
+// Thin wrapper over parseFileWithKind that drops the `kind` (for callers like audit/sbom).
 export function parseFile(file) {
   return parseFileWithKind(file).artifact
 }

package/src/sbom.js

@@ -1,33 +1,21 @@
 import semver from './apis/npm/semver.cjs'
 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.
 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 +26,16 @@ 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`.
 function classifyScope(ecosystem, dir) {
   if (dir === '.') return 'workspace'
   if (ecosystem === 'composer') return 'dependency'
   return dir.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 +46,9 @@ 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.
 export function buildPurl(ecosystem, rawName, version) {
   if (!PURL_TYPES.has(ecosystem)) return null
   let { group, name } = splitName(ecosystem, rawName)
@@ -87,27 +69,17 @@ function compareComponents(a, b) {
   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+version are
+// skipped. 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.
 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) {
@@ -117,8 +89,7 @@ export function collectComponents(artifacts) {
         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 {
@@ -137,31 +108,25 @@ export function collectComponents(artifacts) {
   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.
+// 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}`
 
-// 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.
 export function toSpdx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid = newUuid() } = {}) {
   const { primary, rest } = selectPrimary(components)
   const ordered = primary ? [primary, ...rest] : components
@@ -210,10 +175,8 @@ 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.
 export function toCyclonedx(components, { tool = DEFAULT_TOOL, now = new Date(), uuid = newUuid() } = {}) {
   const { primary, rest } = selectPrimary(components)
   const toComponent = (c) => {
@@ -235,8 +198,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 +211,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)
 }