@exodus/stasis 1.0.0-alpha.2 → 1.0.0-beta.0

package/src/cmd/diff.js

@@ -0,0 +1,36 @@
+import { resolve } from 'node:path'
+
+import { sha512integrity } from '@exodus/stasis-core/state-util'
+import { parseFileWithKind } from '../parse.js'
+import { diffArtifacts, formatDiffStat, hasDifferences } from '../diff.js'
+
+// Run the `stasis diff` CLI command end-to-end: read the two given
+// lockfiles/bundles from disk (this is the layer that pulls in brotli, via
+// `parseFileWithKind`), diff them through the file-free `@exodus/stasis/diff`
+// API, and print the requested view. `left` is the baseline ("from"), `right`
+// the comparison ("to"). Today only the `--stat` summary is implemented, so
+// `stat` is required; the report goes to `out` (stdout by default). With
+// `imports: true` (the `--imports` flag) the report also diffs the resolution
+// graphs — which import edges were added, removed, or redirected.
+//
+// This layer owns the canonical hash: the file-free diff API doesn't pull in
+// `node:crypto`, so we inject `sha512integrity` (the same digest `stasis run`
+// records) for it to re-hash bundle bytes with.
+//
+// Either side may be a lockfile or a bundle, in any combination: a bundle's
+// recorded bytes are re-hashed into the SRI digests a lockfile records, so a
+// lockfile and a bundle compare in the same digest space (see src/diff.js).
+//
+// Returns `{ diff, differences }` so the caller can set the process exit code
+// (non-zero when the artifacts differ, like `diff(1)`).
+export function diffCommand({ cwd = process.cwd(), left, right, stat, imports = false, out = process.stdout } = {}) {
+  if (!left || !right) throw new Error('diff: two files (lockfile or bundle) are required')
+  if (!stat) throw new Error('diff: only --stat is implemented; pass stat: true')
+
+  const a = parseFileWithKind(resolve(cwd, left))
+  const b = parseFileWithKind(resolve(cwd, right))
+  const diff = diffArtifacts(a, b, { imports, hash: sha512integrity })
+
+  out.write(formatDiffStat(diff, { left, right, leftKind: a.kind, rightKind: b.kind }))
+  return { diff, differences: hasDifferences(diff) }
+}

package/src/cmd/extract.js

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { brotliDecompressSync } from 'node:zlib'
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { Lockfile } from '@exodus/stasis-core/lockfile'
+import { sha512integrity } from '@exodus/stasis-core/state-util'
+import { moduleFileKey } from '@exodus/stasis-core/util'
+
+const FILE_LOCK = 'stasis.lock.json'
+
+// Re-derive a Lockfile from an already-parsed Bundle. A bundle records each file's
+// content (UTF-8 source for code / 'resource', base64 for 'resource:base64'); a
+// lockfile records each file's SRI digest -- always taken over the same UTF-8
+// bytes the bundle stored (since the lockfile hashes the lockfile-visible content
+// without decoding). Both
+// share the same per-package bucket shape (name/version/files) plus the
+// entries/config metadata, so the conversion is just "hash each file's bytes"
+// while carrying everything else across verbatim.
+//
+// Requires a v1 bundle: v0 records no package name/version (Bundle.parse infers
+// buckets with null metadata), and Lockfile.serialize must attest both for
+// every node_modules bucket.
+//
+// The digest is taken over the same UTF-8 bytes we write to disk, so it equals
+// what `stasis run --lock=add` would record for the extracted tree and what
+// `stasis prune` recomputes when validating it.
+// Reject a 'resource:base64' content string that isn't canonical base64. Buffer.from
+// silently drops invalid characters and accepts non-canonical padding, so a tampered
+// bundle could ship `XXXX_invalid_chars==` and have the decoded bytes hash to whatever
+// it wanted -- the result would still self-consistently round-trip through `extract`
+// (decode → write → re-hash → match), but the on-disk file would diverge from what
+// any honest producer would have written. Fail closed at the schema-boundary by
+// requiring decode → re-encode to be a fixed point.
+function assertCanonicalBase64(content, file) {
+  const buf = Buffer.from(content, 'base64')
+  if (buf.toString('base64') !== content) {
+    throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
+  }
+  return buf
+}
+
+export function lockfileFromBundle(bundle) {
+  const modules = new Map()
+  for (const [dir, { name, version, ecosystem, files }] of bundle.modules) {
+    const hashed = Object.create(null)
+    for (const [rel, content] of Object.entries(files)) {
+      // The lockfile records sha512 of each file's raw on-disk bytes -- the same
+      // hash `stasis run` produces. The bundle stores 'resource:base64' files as
+      // base64 text, so we decode back to the raw bytes before hashing; code and
+      // 'resource' files are stored as raw UTF-8 and hash identically either way
+      // (Node hashes a string as its UTF-8 bytes). assertCanonicalBase64 closes
+      // the lying-tag hole: a non-canonical base64 string is rejected outright.
+      const file = dir === '.' ? rel : `${dir}/${rel}`
+      const bytes = bundle.formats.get(file) === 'resource:base64'
+        ? assertCanonicalBase64(content, file)
+        : content
+      hashed[rel] = sha512integrity(bytes)
+    }
+    // Carry the dependency `ecosystem` across so the derived lockfile records the
+    // same ecosystem tag the bundle did.
+    modules.set(dir, ecosystem === undefined
+      ? { name, version, files: hashed }
+      : { name, version, ecosystem, files: hashed })
+  }
+  // Carry the bundle's resolution + format maps across so the derived lockfile
+  // attests them too (Bundle.parse already validated the paths) -- without them
+  // the lockfile would be a legacy bytes-only one, and a later frozen run
+  // against the same bundle would skip the resolution/format cross-checks.
+  return new Lockfile({
+    config: bundle.config,
+    entries: bundle.entries,
+    modules,
+    imports: bundle.imports,
+    formats: bundle.formats,
+  })
+}
+
+// Extract a brotli-compressed stasis code bundle (`stasis.code.br`) back onto
+// disk: write every bundled source to `output` (default: cwd), preserving its
+// project-relative path, and drop a matching `stasis.lock.json` alongside them.
+// The lockfile is derived from the bundle's own contents, so the extracted tree
+// validates against it out of the box (e.g. `stasis prune`). For legacy v0
+// bundles only the sources are extracted -- see the in-body comment.
+//
+// Returns `{ dir, files }` where `files` is the number of sources written
+// (the lockfile is not counted).
+export function extractCommand({ cwd = process.cwd(), bundleFile, output } = {}) {
+  if (!bundleFile) throw new Error('extract: a bundle file is required')
+  const bundleAbs = resolve(cwd, bundleFile)
+  if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
+
+  let bundle
+  try {
+    bundle = Bundle.parse(brotliDecompressSync(readFileSync(bundleAbs)).toString('utf-8'))
+  } catch (cause) {
+    // Bundle.parse rejects malformed shapes (e.g. a lockfile JSON fed by mistake,
+    // or a brotli blob that isn't a stasis bundle) with bare message-less asserts;
+    // wrap so the user sees which file failed instead of an empty error.
+    throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
+  }
+
+  // v0 legacy bundles record no package name/version (Bundle.parse infers buckets
+  // with null metadata), so no lockfile can be restored from them:
+  // Lockfile.serialize requires both for every node_modules bucket, and a
+  // null-metadata workspace entry would be rejected later by State.addFile's
+  // name/version cross-check. The sources themselves are still fully
+  // recoverable -- extract them and skip the lockfile, with a warning.
+  const withLockfile = bundle.version === Bundle.VERSION
+
+  const outDir = resolve(cwd, output ?? '.')
+  const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
+  const lockAbs = join(outDir, FILE_LOCK)
+
+  // Plan first, write later: validate every target path and confirm it stays
+  // inside outDir before touching disk, so a malformed bundle can't write a
+  // partial tree. Walk bundle.modules directly rather than the flattening
+  // `sources` getter, which silently last-wins when two buckets collapse to
+  // the same path. Treat the bundle as untrusted input and verify containment
+  // two ways: the resolved path must be BOTH non-escaping relative to outDir
+  // (no leading '..', not absolute -- `relative` returns an absolute path
+  // across Windows drives) AND lexically under `outDir/` (the trailing
+  // separator rejects sibling dirs that merely share outDir as a name prefix,
+  // e.g. `<outDir>-evil`). These checks are lexical only: pre-existing
+  // symlinks inside outDir are followed by the writes, so untrusted bundles
+  // belong in a fresh directory (see doc/extract.md).
+  const writes = []
+  const targets = new Set()
+  for (const [dir, { files }] of bundle.modules) {
+    for (const [rel, content] of Object.entries(files)) {
+      // A `directory` capture (`stasis run --fs`) keys a listing at the directory's
+      // OWN path; it isn't a file to write (its child files recreate the directory),
+      // and writing one would collide with those children at the file-vs-directory
+      // guard below. Skip it on disk -- the derived lockfile still attests its hash
+      // (lockfileFromBundle hashes every bundle entry, directory listings included).
+      // The format is looked up under the canonical key (moduleFileKey, so a
+      // package-ROOT listing's rel==='' resolves to the dir, not `${dir}/`); the
+      // write path below keeps the literal join, so a NON-directory empty file name
+      // still trips the non-canonical-path guard rather than being accepted here.
+      if (bundle.formats.get(moduleFileKey(dir, rel)) === 'directory') continue
+      const file = dir === '.' ? rel : `${dir}/${rel}`
+      if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
+      const abs = resolve(outDir, file)
+      const relToOut = relative(outDir, abs)
+      if (relToOut.startsWith('..') || isAbsolute(relToOut) || !abs.startsWith(outPrefix)) {
+        throw new Error(`extract: bundle path escapes output dir: ${file}`)
+      }
+      // Only canonical paths are accepted: a path that changes under the
+      // resolve+relative round-trip (mid-path '..' or '.', empty segments, an
+      // empty file name) is nothing State or the Solidity bundler ever emit,
+      // and writing it would desync the on-disk tree from the lockfile's
+      // recorded paths.
+      if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
+      if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
+      if (withLockfile && abs === lockAbs) {
+        throw new Error(`extract: bundle contains ${FILE_LOCK}, which would collide with the derived lockfile`)
+      }
+      targets.add(abs)
+      // Resources are decoded back to their original bytes: 'resource:base64' from
+      // base64 (rejected if non-canonical -- a tampered bundle can't ship lying
+      // padding/invalid-char base64), 'resource' (and code) is written as the raw
+      // UTF-8 string.
+      const data = bundle.formats.get(file) === 'resource:base64'
+        ? assertCanonicalBase64(content, file)
+        : content
+      writes.push([abs, data])
+    }
+  }
+  // A planned file may not also be needed as a parent directory of another --
+  // the mkdirSync/writeFileSync pair below would otherwise throw halfway
+  // through the writes.
+  for (const [abs] of writes) {
+    for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) {
+      if (targets.has(d)) {
+        throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
+      }
+    }
+  }
+  const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
+
+  for (const [abs, content] of writes) {
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+  }
+  mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
+  if (withLockfile) writeFileSync(lockAbs, lockText)
+
+  console.warn(`[stasis] Extracted ${writes.length} file(s)${withLockfile ? ` and ${FILE_LOCK}` : ''} to ${outDir}`)
+  if (!withLockfile) {
+    console.warn(`[stasis] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
+  }
+  return { dir: outDir, files: writes.length }
+}

package/src/cmd/sbom.js

@@ -0,0 +1,35 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+import { parseFile } from '../parse.js'
+import { collectComponents, generateSbom } from '../sbom.js'
+
+// Run the `stasis sbom` CLI command end-to-end: read the given lockfiles/bundles
+// from disk (this is the layer that pulls in brotli, via `parseFile`), build an
+// SBOM in the requested `format` (spdx | cyclonedx) through the file-free
+// `@exodus/stasis/sbom` API, and write the pretty-printed JSON to `output` (a
+// file, or stdout when `output` is `-` or unset). The one-line summary goes to
+// stderr so it never corrupts a document streamed to stdout. `now`/`uuid` are
+// injectable for deterministic output.
+export function sbomCommand({ cwd = process.cwd(), files, format, output, now, uuid } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    throw new Error('sbom: at least one lockfile or bundle is required')
+  }
+  const artifacts = files.map((f) => parseFile(resolve(cwd, f)))
+  const components = collectComponents(artifacts)
+  const doc = generateSbom(format, components, { now, uuid })
+  const text = JSON.stringify(doc, undefined, 2) + '\n'
+
+  const target = output ?? '-'
+  if (target === '-') {
+    process.stdout.write(text)
+  } else {
+    const outAbs = resolve(cwd, target)
+    mkdirSync(dirname(outAbs), { recursive: true })
+    writeFileSync(outAbs, text)
+  }
+  const dest = target === '-' ? '<stdout>' : target
+  const n = components.length
+  console.warn(`[stasis] Wrote ${format} SBOM with ${n} component${n === 1 ? '' : 's'} to ${dest}`)
+  return { components, doc }
+}

package/src/diff.js

@@ -0,0 +1,333 @@
+import { sortPaths } from '@exodus/stasis-core/util'
+
+// `@exodus/stasis/diff` — compare two already-parsed stasis artifacts
+// (`Bundle`/`Lockfile` instances) and report what changed, at both the module
+// (package) and the file level. Like `@exodus/stasis/sbom`, it never reads disk
+// and pulls in no brotli (`node:zlib`) or crypto (`node:crypto`): the caller
+// reads/decompresses the artifacts, hands over parsed instances, and — to
+// compare a bundle's bytes against a lockfile's digests — supplies the hash
+// function (see `hash` below). The CLI glue that reads files off disk and wires
+// in `sha512integrity` lives in `src/cmd/diff.js`.
+//
+// The key to comparing across kinds — diffing a lockfile against a bundle — is
+// that every artifact reduces to the same "digest space". A lockfile already
+// records each file as an SRI digest (`sha512-…`); a bundle records the file's
+// bytes, so we re-hash those bytes (via the injected `hash`) into the very
+// digest a lockfile would have recorded. A bundle stores code and 'resource'
+// files as UTF-8 text and 'resource:base64' files as base64 blobs, so the
+// hashing path is decided PER FILE from the bundle's `formats` map -- not
+// from a whole-bundle kind.
+
+const KINDS = new Set(['lockfile', 'bundle'])
+
+// Reduce one file's recorded value to the SRI digest a lockfile records for it.
+// 'lockfile' values are already digests; a bundle's values are file bytes that
+// must be re-hashed. The encoding is now per-file (one bundle holds both code and
+// resources): a 'resource:base64' file is a base64 blob decoded back to raw bytes
+// first, while code files and raw-UTF-8 'resource' files hash as their string. This
+// is the "rehash the bundle" step that lets a bundle and a lockfile be compared,
+// and the reason a `hash` function is required whenever a bundle is involved.
+// `hash` takes a string or Buffer and returns the SRI digest (e.g. the
+// `sha512integrity` the CLI injects); a lockfile needs none.
+function digestOf(kind, format, value, hash) {
+  if (kind === 'lockfile') return value
+  if (typeof hash !== 'function') {
+    throw new Error('diff: a `hash` function is required to compare a bundle (its bytes are re-hashed into a lockfile-style digest)')
+  }
+  if (format === 'resource:base64') return hash(Buffer.from(value, 'base64'))
+  return hash(value)
+}
+
+// Project an artifact onto a uniform shape for diffing: its scope, plus a map of
+// package dir -> { name, version, ecosystem, files: Map<rel, digest> }. `input`
+// is `{ artifact, kind }` where `artifact` is a parsed Bundle/Lockfile and `kind`
+// is 'lockfile' | 'bundle' (see parseFileWithKind). `hash` is the digest function
+// used to re-hash a bundle's bytes; it is only consulted for bundles (a lockfile
+// already holds digests). Per-file encoding is read from the bundle's `formats`.
+export function normalizeArtifact(input, { hash } = {}) {
+  const { artifact, kind } = input ?? {}
+  if (!artifact || !KINDS.has(kind)) {
+    throw new Error("diff: each input must be { artifact, kind } with kind 'lockfile' | 'bundle'")
+  }
+  const formats = artifact.formats ?? new Map()
+  const modules = new Map()
+  for (const [dir, { name, version, ecosystem, files }] of artifact.modules) {
+    const digests = new Map()
+    for (const [rel, value] of Object.entries(files)) {
+      const full = dir === '.' ? rel : `${dir}/${rel}`
+      digests.set(rel, digestOf(kind, formats.get(full), value, hash))
+    }
+    // v0 bundles record no name/version (null); normalize undefined to null too
+    // so module-metadata comparisons have a single "unknown" sentinel.
+    modules.set(dir, { name: name ?? null, version: version ?? null, ecosystem: ecosystem ?? null, files: digests })
+  }
+  return { scope: artifact.config?.scope ?? 'full', modules }
+}
+
+const projectPath = (dir, rel) => (dir === '.' ? rel : `${dir}/${rel}`)
+
+// Diff two artifacts. `left`/`right` are each `{ artifact, kind }`; `left` is the
+// baseline ("from"), `right` the comparison ("to"). Returns a structured report:
+//
+//   {
+//     scope: { left, right },
+//     modules: {
+//       added:   [{ dir, name, version, ecosystem, files }],  // only in right
+//       removed: [{ dir, name, version, ecosystem, files }],  // only in left
+//       changed: [{ dir, name, versionChange?, nameChange? }] // in both, metadata differs
+//     },
+//     files: { added: [path], removed: [path], differing: [path] },
+//     imports?: { attested: { left, right }, added, removed, changed }  // only with { imports: true }
+//   }
+//
+// Modules are compared whole-package; files are compared within packages present
+// on BOTH sides. A package that exists on only one side is reported once as an
+// added/removed module (carrying its file count) rather than re-listing each of
+// its files — so the two levels are complementary, not redundant. A module's
+// `version`/`name` change is only reported when both sides record a (non-null)
+// value, since a v0 bundle records neither.
+//
+// With `{ imports: true }` the diff also compares the artifacts' resolution
+// graphs (the `imports` edges both lockfiles and bundles carry) and reports
+// which edges were added, removed, or redirected — see `diffImports`. It is
+// opt-in because the edge graph is verbose and not always attested.
+//
+// `hash` is the digest function used to re-hash bundle bytes (the CLI passes
+// `sha512integrity`); it is required only when a bundle is one of
+// the operands — a lockfile↔lockfile diff needs none.
+export function diffArtifacts(left, right, { imports = false, hash } = {}) {
+  const L = normalizeArtifact(left, { hash })
+  const R = normalizeArtifact(right, { hash })
+
+  const modulesAdded = []
+  const modulesRemoved = []
+  const modulesChanged = []
+  const filesAdded = []
+  const filesRemoved = []
+  const filesDiffering = []
+
+  const dirs = new Set([...L.modules.keys(), ...R.modules.keys()])
+  for (const dir of dirs) {
+    const l = L.modules.get(dir)
+    const r = R.modules.get(dir)
+    if (l && !r) {
+      modulesRemoved.push({ dir, name: l.name, version: l.version, ecosystem: l.ecosystem, files: l.files.size })
+      continue
+    }
+    if (!l && r) {
+      modulesAdded.push({ dir, name: r.name, version: r.version, ecosystem: r.ecosystem, files: r.files.size })
+      continue
+    }
+
+    // Present on both sides: compare package metadata, then files within.
+    const change = { dir, name: r.name ?? l.name }
+    if (l.version !== null && r.version !== null && l.version !== r.version) {
+      change.versionChange = { from: l.version, to: r.version }
+    }
+    if (l.name !== null && r.name !== null && l.name !== r.name) {
+      change.nameChange = { from: l.name, to: r.name }
+    }
+    if (change.versionChange || change.nameChange) modulesChanged.push(change)
+
+    const rels = new Set([...l.files.keys(), ...r.files.keys()])
+    for (const rel of rels) {
+      const lh = l.files.get(rel)
+      const rh = r.files.get(rel)
+      const path = projectPath(dir, rel)
+      if (lh !== undefined && rh === undefined) filesRemoved.push(path)
+      else if (lh === undefined && rh !== undefined) filesAdded.push(path)
+      else if (lh !== rh) filesDiffering.push(path)
+    }
+  }
+
+  const byDir = (a, b) => sortPaths(a.dir, b.dir)
+  modulesAdded.sort(byDir)
+  modulesRemoved.sort(byDir)
+  modulesChanged.sort(byDir)
+  filesAdded.sort(sortPaths)
+  filesRemoved.sort(sortPaths)
+  filesDiffering.sort(sortPaths)
+
+  const result = {
+    scope: { left: L.scope, right: R.scope },
+    modules: { added: modulesAdded, removed: modulesRemoved, changed: modulesChanged },
+    files: { added: filesAdded, removed: filesRemoved, differing: filesDiffering },
+  }
+  if (imports) result.imports = diffImports(left, right)
+  return result
+}
+
+// The resolution graph an artifact attests, or null when it attests none. A
+// unified bundle always carries a (possibly empty) `imports` Map, so it attests
+// its resolution set -- empty for a resources-only bundle. A lockfile predating
+// resolution attestation records `imports === null` and attests none.
+function attestedImports({ artifact }) {
+  return artifact.imports ?? null
+}
+
+// Collapse an imports map (conditions -> parent -> specifier -> target) to a map
+// of (parent, specifier) -> Set<target>, unioning over every conditions key.
+// We diff at this *resolution* level — "what does this import resolve to?" —
+// rather than at the raw (conditions, parent, specifier) edge key, because the
+// two sides label conditions differently: a statically built bundle records
+// every edge under the wildcard "*", while a runtime lockfile records precise
+// condition sets like "node, import". Keying on conditions would then report a
+// byte-identical resolution as removed (the "*" edge) + added (the precise
+// edge); folding conditions away makes them compare equal. This mirrors how the
+// loader reconciles "*" against precise sets when verifying a resolution
+// (state.js #assertAttestedResolution): the final target is what matters, not
+// how the edge is keyed.
+function resolutionsOf(imports) {
+  const byPair = new Map()
+  for (const [, byParent] of imports) {
+    for (const [parent, specifiers] of byParent) {
+      for (const [specifier, target] of specifiers) {
+        const key = JSON.stringify([parent, specifier])
+        let entry = byPair.get(key)
+        if (!entry) byPair.set(key, (entry = { parent, specifier, targets: new Set() }))
+        // A `--metro` edge target may be a { platform: file } map; fold each
+        // platform's file into the target set, so a redirect is compared at the
+        // "what files does this resolve to" level regardless of platform keying.
+        if (target instanceof Map) for (const f of target.values()) entry.targets.add(f)
+        else entry.targets.add(target)
+      }
+    }
+  }
+  return byPair
+}
+
+const cmpStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0)
+const cmpPair = (a, b) => sortPaths(a.parent, b.parent) || cmpStr(a.specifier, b.specifier)
+const sortedTargets = (set) => [...set].toSorted(sortPaths)
+const sameTargets = (a, b) => a.size === b.size && [...a].every((t) => b.has(t))
+
+// Diff the resolution graphs at the (parent, specifier) level (see
+// `resolutionsOf` for why conditions are folded away). Each side maps a
+// (parent, specifier) to the set of files it resolves to (usually one). Reports:
+//   added   — a (parent, specifier) only the right artifact resolves
+//   removed — a (parent, specifier) only the left artifact resolves
+//   changed — resolved on both sides, but to a different set of targets (a
+//             redirect — the kind of change a byte/format diff can't see)
+// `from`/`to` are sorted arrays of target files. When either side does not
+// attest imports at all (a legacy lockfile predating `imports`), the
+// comparison is skipped and `attested` flags why, rather than reporting one
+// side's whole graph as added/removed.
+export function diffImports(left, right) {
+  const li = attestedImports(left)
+  const ri = attestedImports(right)
+  const attested = { left: li !== null, right: ri !== null }
+  if (li === null || ri === null) return { attested, added: [], removed: [], changed: [] }
+
+  const L = resolutionsOf(li)
+  const R = resolutionsOf(ri)
+  const added = []
+  const removed = []
+  const changed = []
+  for (const key of new Set([...L.keys(), ...R.keys()])) {
+    const l = L.get(key)
+    const r = R.get(key)
+    if (l && !r) removed.push({ parent: l.parent, specifier: l.specifier, from: sortedTargets(l.targets) })
+    else if (!l && r) added.push({ parent: r.parent, specifier: r.specifier, to: sortedTargets(r.targets) })
+    else if (!sameTargets(l.targets, r.targets)) {
+      changed.push({ parent: l.parent, specifier: l.specifier, from: sortedTargets(l.targets), to: sortedTargets(r.targets) })
+    }
+  }
+  added.sort(cmpPair)
+  removed.sort(cmpPair)
+  changed.sort(cmpPair)
+  return { attested, added, removed, changed }
+}
+
+// True when the diff records any module-, file-, or (when present) import-level
+// change. Scope alone is informational (a scope difference shows up as the
+// modules/files only one side records) and does not, on its own, count as a
+// difference. Imports that can't be compared (one side doesn't attest them)
+// contribute nothing — their add/remove/change lists are empty.
+export function hasDifferences(diff) {
+  const { modules, files, imports } = diff
+  let n =
+    modules.added.length + modules.removed.length + modules.changed.length +
+    files.added.length + files.removed.length + files.differing.length
+  if (imports) n += imports.added.length + imports.removed.length + imports.changed.length
+  return n > 0
+}
+
+const KIND_LABEL = { lockfile: 'lockfile', bundle: 'bundle' }
+const plural = (n) => (n === 1 ? '' : 's')
+const ident = ({ name, version }) => (name ? (version ? `${name}@${version}` : name) : '')
+
+// Diff markers. `~` reads too close to `-` in a terminal, so a changed/redirected
+// entry is marked `*` (distinct from `-` removed / `+` added).
+const REMOVED = '-'
+const ADDED = '+'
+const CHANGED = '*'
+
+function describeModuleChange({ name, versionChange, nameChange }) {
+  const segs = []
+  if (versionChange) segs.push(`${versionChange.from} -> ${versionChange.to}`)
+  if (nameChange) segs.push(`name ${nameChange.from} -> ${nameChange.to}`)
+  return `${name ? `${name} ` : ''}${segs.join(', ')}`
+}
+
+const moduleLine = (mark, x) => {
+  const id = ident(x)
+  return `  ${mark} ${x.dir}${id ? `  ${id}` : ''} (${x.files} file${plural(x.files)})`
+}
+
+// `parent  'specifier'` — conditions are folded away (see resolutionsOf), so an
+// edge is identified by the importing file and the specifier it resolved.
+const edgeLabel = (e) => `${e.parent}  '${e.specifier}'`
+const targetList = (files) => files.join(', ')
+
+// Render the `--stat` summary of a diff (module + file change lists with
+// counts, plus the import-edge changes when the diff carries them), in the
+// spirit of `git diff --stat`: it reports *what* changed, not the differing
+// text itself, and the whole report — including the trailing differ/no-differ
+// line — goes to stdout. `labels` is `{ left, right, leftKind, rightKind }` for
+// the header. Lines use `-` (only in left / baseline), `+` (only in right),
+// `*` (changed in place). Returns a string ending in a newline.
+export function formatDiffStat(diff, { left = '(left)', right = '(right)', leftKind, rightKind } = {}) {
+  const { modules: m, files: f, imports: im, scope } = diff
+  const lines = ['stasis diff --stat']
+  const label = (kind) => (kind ? `${KIND_LABEL[kind]}, ` : '')
+  lines.push(`  ${REMOVED} ${left} (${label(leftKind)}scope=${scope.left})`)
+  lines.push(`  ${ADDED} ${right} (${label(rightKind)}scope=${scope.right})`)
+  if (scope.left !== scope.right) {
+    lines.push(`  note: scopes differ (${scope.left} vs ${scope.right}); files only the full-scope artifact records show as removed/added`)
+  }
+
+  lines.push('')
+  lines.push(`Modules: ${m.added.length} added, ${m.removed.length} removed, ${m.changed.length} changed`)
+  for (const x of m.removed) lines.push(moduleLine(REMOVED, x))
+  for (const x of m.added) lines.push(moduleLine(ADDED, x))
+  for (const x of m.changed) lines.push(`  ${CHANGED} ${x.dir}  ${describeModuleChange(x)}`)
+
+  lines.push('')
+  // Counts cover files *within modules present on both sides*; files inside a
+  // wholly added/removed module are summarized by its module entry above (with
+  // a file count), not re-counted here — so name the scope to avoid misreading
+  // "0 removed" when a whole package vanished.
+  lines.push(`Files (within shared modules): ${f.added.length} added, ${f.removed.length} removed, ${f.differing.length} differing`)
+  for (const p of f.removed) lines.push(`  ${REMOVED} ${p}`)
+  for (const p of f.added) lines.push(`  ${ADDED} ${p}`)
+  for (const p of f.differing) lines.push(`  ${CHANGED} ${p}`)
+
+  if (im) {
+    lines.push('')
+    if (!im.attested.left || !im.attested.right) {
+      const which = !im.attested.left && !im.attested.right
+        ? 'neither artifact attests'
+        : `${im.attested.left ? right : left} does not attest`
+      lines.push(`Imports: ${which} resolutions; skipping import diff`)
+    } else {
+      lines.push(`Imports: ${im.added.length} added, ${im.removed.length} removed, ${im.changed.length} changed`)
+      for (const e of im.removed) lines.push(`  ${REMOVED} ${edgeLabel(e)} -> ${targetList(e.from)}`)
+      for (const e of im.added) lines.push(`  ${ADDED} ${edgeLabel(e)} -> ${targetList(e.to)}`)
+      for (const e of im.changed) lines.push(`  ${CHANGED} ${edgeLabel(e)}  ${targetList(e.from)} -> ${targetList(e.to)}`)
+    }
+  }
+
+  lines.push('')
+  lines.push(hasDifferences(diff) ? 'Artifacts differ' : 'No differences')
+  return lines.join('\n') + '\n'
+}

package/src/esbuild.js

@@ -1,56 +1,5 @@
-import { readFile } from 'node:fs/promises'
-import { isUtf8 } from 'node:buffer'
-import { extname } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import assert from 'node:assert/strict'
-
-import { State } from './state.js'
-
-const state = State.instance
-assert.ok(state, 'Stasis preload is not active')
-
-export class StasisEsbuild {
-  #seen = new Set()
-
-  get name() {
-    return 'stasis'
-  }
-
-  setup = ({ onResolve, onLoad, resolve }) => {
-    onResolve({ filter: /$/, namespace: 'file' }, async ({ path: specifier, ...args }) => {
-      // Recurse with a synthetic namespace so esbuild's default resolver runs without re-entering us
-      const res = await resolve(specifier, { ...args, namespace: 'stasis' })
-      if (res.errors.length > 0) return res
-      assert.equal(res.warnings.length, 0)
-      assert.equal(res.suffix, '')
-
-      const isEntry = !args.importer
-      if (res.namespace === 'file' && !res.external) {
-        if (!isEntry) {
-          const parentURL = pathToFileURL(args.importer).toString()
-          const url = pathToFileURL(res.path).toString()
-          state.addImport(parentURL, specifier, url)
-        }
-      }
-
-      return { ...res, pluginData: { ...res.pluginData, isEntry } }
-    })
-
-    onLoad({ filter: /$/, namespace: 'file' }, async ({ path, pluginData, with: attrs }) => {
-      assert.equal(Object.keys(attrs).length, 0) // TODO: 'with' statements
-      const source = await readFile(path)
-      const isBinary = !isUtf8(source)
-
-      if (!this.#seen.has(path)) {
-        this.#seen.add(path)
-        state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, isBinary })
-      }
-
-      if (isBinary) return { contents: source, loader: 'binary' }
-
-      const loader = extname(path).replace(/^\.[cm]?/, '')
-      assert(['js', 'ts', 'jsx', 'tsx', 'json'].includes(loader))
-      return { contents: source, loader }
-    })
-  }
-}
+// Public-export adapter: backs `@exodus/stasis/esbuild`. The plugin lives in
+// @exodus/stasis-plugins (which depends on @exodus/stasis-core for State /
+// resolvePluginState). Internal code uses `@exodus/stasis-plugins/esbuild` directly;
+// this file exists only to back the package's `exports` map.
+export * from '@exodus/stasis-plugins/esbuild'