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

package/src/cmd/diff.js

@@ -4,25 +4,8 @@ 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)`).
+// Run `stasis diff`: read both lockfiles/bundles from disk and diff them through
+// the file-free diff API. Returns { diff, differences } for the caller's exit code.
 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')

package/src/cmd/sbom.js

@@ -4,13 +4,7 @@ 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.
+// The one-line summary goes to stderr so it never corrupts an SBOM streamed to stdout.
 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')

package/src/diff.js

@@ -1,34 +1,15 @@
 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.
+// `@exodus/stasis/diff` — compare two parsed stasis artifacts (Bundle/Lockfile) at the module and
+// file level. Never reads disk. Comparing across kinds works by reducing every file to the same
+// digest space: a lockfile already holds SRI digests; a bundle holds bytes, re-hashed via the
+// injected `hash` — so a `hash` function is required whenever a bundle is an operand. Per-file
+// encoding (resource:base64 vs text) is read from the bundle's `formats` map.
 
 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.
+// Reduce one file's recorded value to an SRI digest: lockfile values already are digests; a
+// bundle's are re-hashed, with a `resource:base64` file decoded to bytes first (others hash as text).
 function digestOf(kind, format, value, hash) {
   if (kind === 'lockfile') return value
   if (typeof hash !== 'function') {
@@ -38,12 +19,8 @@ function digestOf(kind, format, value, hash) {
   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`.
+// Project an artifact onto a uniform shape: scope + Map<dir, { name, version, ecosystem,
+// files: Map<rel, digest> }>. `input` is { artifact, kind }; `hash` re-hashes bundle bytes only.
 export function normalizeArtifact(input, { hash } = {}) {
   const { artifact, kind } = input ?? {}
   if (!artifact || !KINDS.has(kind)) {
@@ -57,44 +34,21 @@ export function normalizeArtifact(input, { hash } = {}) {
       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.
+    // v0 bundles record no name/version; normalize undefined -> null for 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 }
+  // `executable` decides which files `stasis extract` chmods +x, so a change to it changes the tree
+  // an artifact produces even when every digest matches -- it has to be part of "did these differ?".
+  return { scope: artifact.config?.scope ?? 'full', modules, executable: artifact.executable ?? new Set() }
 }
 
 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.
+// Diff two `{ artifact, kind }` operands (`left` = baseline/"from", `right` = "to"). Modules are
+// compared whole-package; files only within packages present on BOTH sides (a one-sided package is
+// reported once as an added/removed module, not per-file). A version/name change is reported only
+// when both sides record a non-null value. `{ imports: true }` also diffs the resolution graphs
+// (opt-in; verbose). `hash` is required only when a bundle is an operand.
 export function diffArtifacts(left, right, { imports = false, hash } = {}) {
   const L = normalizeArtifact(left, { hash })
   const R = normalizeArtifact(right, { hash })
@@ -119,7 +73,6 @@ export function diffArtifacts(left, right, { imports = false, hash } = {}) {
       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 }
@@ -148,35 +101,32 @@ export function diffArtifacts(left, right, { imports = false, hash } = {}) {
   filesRemoved.sort(sortPaths)
   filesDiffering.sort(sortPaths)
 
+  // Execute-bit changes, reported for every path either side marks (not just files in shared
+  // modules): gaining or losing +x is a real change to the extracted tree, whatever bucket it sits in.
+  const onlyIn = (a, b) => [...a].filter((file) => !b.has(file)).toSorted(sortPaths)
+  const executableAdded = onlyIn(R.executable, L.executable)
+  const executableRemoved = onlyIn(L.executable, R.executable)
+
   const result = {
     scope: { left: L.scope, right: R.scope },
     modules: { added: modulesAdded, removed: modulesRemoved, changed: modulesChanged },
     files: { added: filesAdded, removed: filesRemoved, differing: filesDiffering },
+    executable: { added: executableAdded, removed: executableRemoved },
   }
   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.
+// The resolution graph an artifact attests, or null when it attests none (a legacy lockfile
+// predating attestation); a bundle always carries a possibly-empty map.
 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.
+// Collapse an imports map (conditions -> parent -> specifier -> target) to (parent, specifier) ->
+// Set<target>, unioning over conditions: a static bundle keys every edge under "*" while a runtime
+// lockfile uses precise sets, so keying on conditions would report identical resolutions as
+// removed+added. Folding conditions away makes them compare equal.
 function resolutionsOf(imports) {
   const byPair = new Map()
   for (const [, byParent] of imports) {
@@ -185,9 +135,7 @@ function resolutionsOf(imports) {
         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.
+        // A `--metro` edge target may be a { platform: file } map; fold each platform's file into the set.
         if (target instanceof Map) for (const f of target.values()) entry.targets.add(f)
         else entry.targets.add(target)
       }
@@ -201,17 +149,10 @@ const cmpPair = (a, b) => sortPaths(a.parent, b.parent) || cmpStr(a.specifier, b
 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.
+// Diff resolution graphs at the (parent, specifier) level (conditions folded away — see
+// resolutionsOf). Reports added/removed and changed (resolved on both sides to different targets —
+// a redirect a byte diff can't see). When either side doesn't attest imports, the diff is skipped
+// and `attested` flags why, rather than reporting one whole graph as added/removed.
 export function diffImports(left, right) {
   const li = attestedImports(left)
   const ri = attestedImports(right)
@@ -238,16 +179,17 @@ export function diffImports(left, right) {
   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.
+// True when the diff records any module-, file-, or import-level change. Scope alone is
+// informational and doesn't count (unattested imports contribute empty lists).
 export function hasDifferences(diff) {
-  const { modules, files, imports } = diff
+  // `executable` is unguarded like modules/files -- diffArtifacts always sets it, and a shape guard
+  // here would make a renamed facet read as "no differences" and quietly pass a review gate.
+  // `imports` is genuinely opt-in (the `imports` option), so it keeps its guard.
+  const { modules, files, executable, imports } = diff
   let n =
     modules.added.length + modules.removed.length + modules.changed.length +
-    files.added.length + files.removed.length + files.differing.length
+    files.added.length + files.removed.length + files.differing.length +
+    executable.added.length + executable.removed.length
   if (imports) n += imports.added.length + imports.removed.length + imports.changed.length
   return n > 0
 }
@@ -256,8 +198,7 @@ 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).
+// Diff markers: `*` (changed) — `~` reads too close to `-` in a terminal.
 const REMOVED = '-'
 const ADDED = '+'
 const CHANGED = '*'
@@ -274,20 +215,15 @@ const moduleLine = (mark, 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.
+// `parent  'specifier'` — an edge is identified by importer + specifier (conditions folded away).
 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.
+// Render the `--stat` summary (module + file change lists with counts, plus import-edge changes
+// when present); reports what changed, not the text. `labels` is { left, right, leftKind, rightKind }.
+// 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 { modules: m, files: f, executable: ex, 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})`)
@@ -303,15 +239,22 @@ export function formatDiffStat(diff, { left = '(left)', right = '(right)', leftK
   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.
+  // Counts cover only files within modules present on both sides; a wholly added/removed module's
+  // files are summarized by its module entry above — hence the "within shared modules" label.
   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}`)
 
+  // Only rendered when something changed: an unchanged execute-bit set is the overwhelming norm,
+  // and a permanent "0 added, 0 removed" line would be noise in every diff.
+  if (ex.added.length > 0 || ex.removed.length > 0) {
+    lines.push('')
+    lines.push(`Executable: ${ex.added.length} added, ${ex.removed.length} removed`)
+    for (const p of ex.removed) lines.push(`  ${REMOVED} ${p}`)
+    for (const p of ex.added) lines.push(`  ${ADDED} ${p}`)
+  }
+
   if (im) {
     lines.push('')
     if (!im.attested.left || !im.attested.right) {

package/src/loader-mock.js

@@ -1,19 +1,12 @@
-// stasis's `--mock` run-time loader entry (used by `stasis run --mock`). The
-// import order is load-bearing:
-//   1. the @exodus/stasis-core hooks lib -- evaluating it snapshots stasis's own
-//      node:fs/path/etc. bindings off the *real* builtins (state.js destructures
-//      them at module-eval time), so stasis keeps reading/writing through real fs;
-//   2. ./mock.js -- which neutralizes the network/timer builtins and fs writers in
-//      JS and calls module.syncBuiltinESMExports() so user code's later ESM imports
-//      resolve to the mocked builtins.
-// Only THEN install() the hooks. Running mock.js before registration keeps it from
-// going through the hooks (so it never becomes the bundle entry), and running it
-// after the lib's snapshots leaves stasis's own bindings untouched. This static
-// composition is what lets core stay mock-agnostic with no env-var coordination.
+// stasis's `--mock` loader entry. The import order is load-bearing:
+//   1. the core hooks lib -- evaluating it snapshots stasis's own fs bindings off the *real*
+//      builtins, so stasis keeps reading/writing through real fs;
+//   2. ./mock.js -- neutralizes the network/timer builtins and fs writers, then calls
+//      syncBuiltinESMExports() so user code's later ESM imports resolve to the mocks.
+// Only THEN install() the hooks (so mock.js never goes through them / becomes the bundle entry).
 import { install } from '@exodus/stasis-core/hooks'
-// `export *` (mock.js has no exports) rather than a bare side-effect import only
-// to satisfy the no-unassigned-import lint rule; ESM still evaluates it here, in
-// source order, after the hooks lib above and before install() below.
+// `export *` (mock.js has no exports) rather than a bare side-effect import, to satisfy the
+// no-unassigned-import lint rule; ESM still evaluates it here in source order.
 export * from './mock.js'
 
 install()

package/src/loaders/bash.js

@@ -1,13 +1,8 @@
-// Bash loader: produces a `{ sources, resolutions, missing }` triple from a
-// set of shell scripts, mirroring the Solidity loader's interface (see
-// ./solidity.js). A reference to a .sh/.bash file by a path that lands INSIDE
-// the bundle root (`./lib.sh`, `dir/lib.sh`) must resolve to an in-set script;
-// when it doesn't it lands in `missing` so the bundle builder can reject the
-// dangling dependency. Everything else is best-effort and dropped: PATH
-// commands (`grep`), `$VAR` paths, extensionless `source ./env`, absolute
-// `source /etc/x.sh`, and `../` paths that escape the root — none is bundle-able.
-// A `source "${VAR}/x.sh"` whose path can't be evaluated statically is picked
-// up from its `# shellcheck source=...` directive when one is present.
+// Bash loader: `{ sources, resolutions, missing }` from a set of scripts. A
+// .sh/.bash reference landing INSIDE the bundle root must resolve to an in-set
+// script, else it lands in `missing`; everything else (PATH commands, `$VAR`
+// paths, absolute/escaping paths) is best-effort and dropped. A dynamically
+// sourced path can be pinned by a `# shellcheck source=...` directive.
 
 import { realpathSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -15,16 +10,13 @@ import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path
 
 import { assertRealPathWithinBase } from '@exodus/stasis-core/util'
 
-// The capture class excludes `` ` ``, `(`, `)` (on top of whitespace, quotes,
-// `;`, `&`, `|`, `#`) so a reference inside a command substitution —
-// `` `source x.sh` `` or `$(bash x.sh)` — doesn't swallow the closing delimiter
-// into the path (which would silently drop the edge from the bundle).
+// The capture class excludes backtick/`(`/`)` so a ref inside a command
+// substitution (`` `source x.sh` ``, `$(bash x.sh)`) doesn't swallow the closing delimiter.
 
 // `source script.sh`, `. script.sh`, `. ./script.sh`
 const SOURCE_RE = /(?:^|\n|;|&&|\|\||`|\$\()\s*(?:source|\.)\s+["']?([^\s"';&|#`()]+)["']?/gu
 
-// `bash script.sh`, `sh script.sh`, `/usr/bin/env bash script.sh`,
-// `/bin/sh script.sh`, `/usr/bin/bash script.sh`, etc.
+// `bash`/`sh script.sh`, incl. `/usr/bin/env bash`, `/bin/sh`, `/usr/bin/bash`.
 const EXEC_RE = /(?:^|\n|;|&&|\|\||`|\$\()\s*(?:\/usr\/bin\/env\s+|\/bin\/|\/usr\/bin\/)?(?:ba)?sh\s+["']?([^\s"';&|#`()]+)["']?/gu
 
 // Direct invocation: `./script.sh`, `../lib/helper.bash`, `/path/to/script.sh`
@@ -33,21 +25,13 @@ const DIRECT_RE = /(?:^|\n|;|&&|\|\||`|\$\()\s*["']?(\.\.?\/[^\s"';&|#`()]+\.(?:
 // Dependency hint comment: `# Depends on: example.sh`
 const COMMENT_RE = /^# Depends on: ([^ ]+\.(?:sh|bash))( |$)/gmu
 
-// shellcheck `source=` directive: `# shellcheck source=../lib/config.sh`
-// (optionally alongside other directives, e.g. `# shellcheck disable=SC1091 source=lib/x.sh`).
-// This is the standard, explicit way to tell tooling where a dynamically
-// sourced file lives — e.g. `source "${LIB_DIR}/config.sh"`, whose path is a
-// `$VAR` expansion that can't be evaluated statically. The path is resolved
-// relative to the script (matching shellcheck's default). `source=/dev/null`
-// is shellcheck's "don't follow this source" sentinel and is ignored below.
+// shellcheck `source=` directive: `# shellcheck source=../lib/config.sh`, the
+// explicit way to point at a dynamically sourced (`$VAR`) file. Resolved relative
+// to the script. `source=/dev/null` is shellcheck's "don't follow" sentinel, ignored below.
 const SHELLCHECK_SOURCE_RE = /#\s*shellcheck\s[^\n]*?\bsource=["']?([^\s"'#]+)["']?/gu
 
-// Extract every file-like reference from a script's text. Variable
-// expansions (`$VAR`, `${VAR}`, `$HOME/x.sh`) and flags (`-c`) are dropped
-// here — they are never bundle-able file paths; a `source "${VAR}/x.sh"` whose
-// real location can't be computed statically should carry a `# shellcheck
-// source=` directive instead. The remaining strings are candidate references;
-// resolveBashCall decides which name a real file.
+// Extract candidate file references. `$VAR` expansions and `-flags` are dropped
+// (never bundle-able); resolveBashCall decides which of the rest name a real file.
 export function extractBashCalls(content) {
   const calls = new Set()
   for (const re of [SOURCE_RE, EXEC_RE, DIRECT_RE, COMMENT_RE, SHELLCHECK_SOURCE_RE]) {
@@ -60,26 +44,9 @@ export function extractBashCalls(content) {
   return [...calls]
 }
 
-// Resolve a bash reference to a baseDir-relative POSIX path. Existence is
-// checked against `knownFiles` (tree mode, used once every script is in
-// hand) or the filesystem under `baseDir` (walk mode, while discovering the
-// graph); with neither, only path computation happens and unvalidated names
-// return null.
-//
-// Reference kinds are treated differently:
-//   - absolute (`/x`): mapped to project-relative by stripping the leading
-//     slash, accepted only if that file actually exists in the set/on disk
-//     (so system paths like /etc/profile.d/x.sh are dropped, not bundled).
-//   - relative / project-relative WITH a slash (`./x`, `../x`, `lib/x.sh`):
-//     resolved against the caller's directory and returned as a computed
-//     path WITHOUT an existence check — the walk's readFile surfaces a
-//     missing target and the tree flags or drops it, mirroring the Solidity
-//     loader. Traversal above baseDir returns null rather than clamping, so
-//     an escaping `../x.sh` is treated as external (never flagged missing).
-//   - bare name (`helper.sh`, but also `grep`, `node`): could be a sibling
-//     script or a PATH command, so it is accepted only when it names a real
-//     file — caller's dir, then project root, then (knownFiles only) any
-//     in-set file by basename.
+// Resolve a bash reference to a baseDir-relative POSIX path. Existence is checked
+// against `knownFiles` (tree mode) or the filesystem under `baseDir` (walk mode);
+// with neither, only path computation happens. Handling differs by kind (below).
 export function resolveBashCall(ref, fromFile, { knownFiles, baseDir } = {}) {
   const present = (p) => {
     if (!p) return false
@@ -110,13 +77,13 @@ export function resolveBashCall(ref, fromFile, { knownFiles, baseDir } = {}) {
     return out.join('/') || null
   }
 
-  // Absolute → project-relative, validated.
+  // Absolute → project-relative, accepted only if it exists (so `/etc/...` is dropped).
   if (ref.startsWith('/')) {
     const stripped = ref.replace(/^\/+/u, '')
     return present(stripped) ? stripped : null
   }
 
-  // Path with a slash → computed, validation deferred to the caller.
+  // Path with a slash → computed against the caller's dir; existence deferred to the caller.
   if (ref.includes('/')) return resolveRel(ref)
 
   // Bare name → only accept a real file.
@@ -132,19 +99,13 @@ export function resolveBashCall(ref, fromFile, { knownFiles, baseDir } = {}) {
   return null
 }
 
-// A `.sh`/`.bash` extension marks a reference as a shell script (as opposed to
-// an extensionless `source ./env`, which we don't treat as a missing script
-// when absent).
+// True for `.sh`/`.bash` refs; an extensionless `source ./env` isn't flagged missing when absent.
 const hasShellScriptExt = (ref) => ref.endsWith('.sh') || ref.endsWith('.bash')
 
-// Build the { sources, resolutions, missing } triple from a Map of
-// already-loaded scripts. A reference is recorded in `missing` (which the
-// bundle builder treats as fatal) only when it resolves to a path INSIDE the
-// bundle root that wasn't collected — i.e. a dangling `source ./lib.sh`.
-// References that resolve to null are external and tolerated: bare names
-// (PATH commands / runtime-cwd scripts), absolute `/etc/...` paths, `$VAR`
-// paths, and `../` paths that escape the root — none can live in the bundle.
-// Self-references and non-script extensions are dropped without flagging.
+// Build the triple from already-loaded scripts. A ref is `missing` (fatal) only
+// when it resolves INSIDE the bundle root but wasn't collected (a dangling
+// `source ./lib.sh`); null-resolving refs are external and tolerated, and
+// self-refs/non-script exts are dropped silently.
 export function buildBashTree(sources) {
   const knownFiles = new Set(sources.keys())
   const resolutions = new Map()
@@ -152,9 +113,8 @@ export function buildBashTree(sources) {
   for (const [path, content] of sources) {
     const specMap = new Map()
     for (const ref of extractBashCalls(content)) {
-      // In tree mode the slash branch returns a computed in-bundle path
-      // without checking existence, so a non-null target that isn't a known
-      // file is a genuine dangling local dependency; a null target is external.
+      // Slash branch returns an unchecked in-bundle path, so a non-null target not
+      // in knownFiles is a genuine dangling dep; a null target is external.
       const target = resolveBashCall(ref, path, { knownFiles })
       if (target && knownFiles.has(target)) {
         if (target !== path) specMap.set(ref, target) // drop self-references
@@ -168,12 +128,8 @@ export function buildBashTree(sources) {
   return { sources, resolutions, missing }
 }
 
-// Walk the filesystem from `entries`, following resolved source/exec/direct
-// references and reading each reachable script exactly once. Files in the
-// same wave are read in parallel; the next wave depends on references found
-// in the previous one. A reference that resolves to a path missing on disk
-// warns and is skipped (the graph stays partial but the walk continues);
-// unresolved references (commands, dynamic paths) are silently ignored.
+// Walk from `entries` following resolved refs, reading each script once; a ref
+// missing on disk warns and is skipped without aborting the walk.
 export async function collectBashFilesFromDisk(baseDir, entries) {
   const sources = new Map()
   const realBase = realpathSync(baseDir)
@@ -191,8 +147,7 @@ export async function collectBashFilesFromDisk(baseDir, entries) {
             console.warn(`[loader.bash] Missing file: ${relPath}`)
             return null
           }
-          // A slash-bearing ref can resolve to a directory (e.g. `source ./lib`);
-          // readFile then throws EISDIR. Skip it rather than aborting the walk.
+          // A slash ref can resolve to a directory (`source ./lib`) → EISDIR; skip, don't abort.
           if (err.code === 'EISDIR') {
             console.warn(`[loader.bash] Skipping directory reference: ${relPath}`)
             return null
@@ -218,9 +173,8 @@ export async function collectBashFilesFromDisk(baseDir, entries) {
   return sources
 }
 
-// Reject absolute paths and `..`-escaping paths in a `.sh.txt` listing so a
-// malicious or sloppy listing can't trick the loader into reading arbitrary
-// files outside the listing's own directory.
+// Reject absolute and `..`-escaping paths in a `.sh.txt` listing so it can't
+// read files outside the listing's own directory.
 function assertWithinBase(baseDir, candidate, label) {
   if (isAbsolute(candidate)) throw new Error(`${label} must not be absolute: ${candidate}`)
   const rel = relative(baseDir, resolve(baseDir, candidate)).split(/[\\/]/u).join('/')
@@ -229,11 +183,9 @@ function assertWithinBase(baseDir, candidate, label) {
   }
 }
 
-// High-level: takes a `.sh.txt` listing file whose lines are the scripts to
-// load (`.sh`, `.bash`, or extensionless), resolved relative to the listing.
-// Unlike loadSolidity, the listing is the authoritative manifest — bash
-// sourcing is too dynamic to walk reliably — so exactly the listed files are
-// read and resolutions are computed among them. Returns { sources, resolutions, missing }.
+// High-level entry: reads the scripts named in a `.sh.txt` listing (relative to
+// it). Unlike loadRust, the listing is authoritative — bash sourcing is too
+// dynamic to walk — so exactly the listed files are read, resolutions computed among them.
 export async function loadBash(shTxtFile) {
   const baseDir = dirname(resolve(shTxtFile))
   const listing = await readFile(shTxtFile, 'utf8')