@exodus/stasis 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exodus Movement
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# `@exodus/stasis`
+
+Analyzeable source code bundles with resolutions + per-file lockfiles
+
+## Bundles
+
+## Lockfiles
+
+## License
+
+[MIT](./LICENSE)

package/bin/stasis.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { parseArgs } from 'node:util'
+import { once } from 'node:events'
+import { fileURLToPath } from 'node:url'
+import { basename, resolve } from 'node:path'
+import { existsSync, realpathSync } from 'node:fs'
+import assert from 'node:assert/strict'
+import pkg from '../package.json' with { type: 'json' }
+
+const argv = [...process.argv]
+assert(['node', 'node.exe'].includes(basename(argv.shift())))
+assert(['node', 'node.exe'].includes(basename(process.argv0)))
+
+const jsname = argv.shift()
+const pathsEqual = (a, b) => a === b || (existsSync(a) && realpathSync(a) === b) // resolve symlinks
+assert(basename(jsname) === 'stasis' || pathsEqual(jsname, fileURLToPath(import.meta.url)))
+
+function usage(prefix = '') {
+  console.error(`${prefix}\nUsage:
+ stasis run --lock=(add|replace|frozen|ignore) [--bundle=(add|replace|load|ignore)] [--bundle-file=path/to/bundle.br] [--full] path/to/file.js ...
+ stasis bundle create path/to/lockfile
+ stasis bundle verify path/to/lockfile
+ stasis prune [path/to/project]
+ stasis audit path/to/file ...
+`.trim())
+  process.exit(1)
+}
+
+function setEnv(name, value) {
+  const env = process.env[name]
+  if (env && env !== value) throw new Error(`env conflict: ${name}="${env}", effective: "${value}"`)
+  process.env[name] = value === undefined ? '' : value
+}
+
+const command = argv.shift()
+
+if (command === '-v' || command === '--version') {
+  console.log(`v${pkg.version}`)
+  process.exit(0)
+} else if (command === 'run') {
+  const flags = []
+  const valueFlags = new Set(['--bundle', '--bundle-file', '--lock'])
+  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
+    flags.push(argv.shift())
+  }
+
+  const options = {
+    lock: { type: 'string', default: 'none' },
+    bundle: { type: 'string', default: 'none' },
+    'bundle-file': { type: 'string' },
+    debug: { type: 'boolean' },
+    full: { type: 'boolean' },
+  }
+
+  const { values } = parseArgs({ args: flags, options })
+  if (argv.length === 0) usage('Nothing to run: no path to file given')
+  if (!['none', 'ignore', 'add', 'replace', 'frozen'].includes(values.lock)) usage('Error: invalid --lock value')
+  const lock = values.lock
+  const scope = values.full ? 'full' : 'node_modules'
+  const bundle = values.bundle
+  const bundleFile = values['bundle-file'] ? resolve(values['bundle-file']) : ''
+  const debug = values.debug ? '1' : ''
+  if (!['none', 'ignore', 'add', 'replace', 'load'].includes(bundle)) usage('Error: invalid --bundle value')
+  if (bundleFile && bundle === 'none') usage('Error: --bundle-file requires --bundle=(add|replace|load|ignore)')
+  if (bundle === 'load' && lock !== 'frozen' && lock !== 'none' && lock !== 'ignore') usage('Error: --bundle=load requires --lock=(frozen|none|ignore)')
+  if (lock === 'none' && bundle === 'none') usage('Error: --lock=none requires --bundle=(add|replace|load|ignore)')
+  console.warn('[stasis] Running stasis with config:', { lock, scope, bundle, ...(bundleFile && { bundleFile }) })
+  if (debug) console.warn(`[stasis] Warning: stasis debug mode active`)
+  setEnv('EXODUS_STASIS_LOCK', lock)
+  setEnv('EXODUS_STASIS_SCOPE', scope)
+  setEnv('EXODUS_STASIS_BUNDLE', bundle)
+  setEnv('EXODUS_STASIS_BUNDLE_FILE', bundleFile)
+  setEnv('EXODUS_STASIS_DEBUG', debug)
+  const child = spawn('node', ['--import', import.meta.resolve('../src/loader.js'), ...argv], { stdio: 'inherit' })
+  const [code] = await once(child, 'close')
+  process.exitCode = code
+} else if (command === 'bundle') {
+  usage('bundle command is not implemented yet')
+} else if (command === 'prune') {
+  if (argv.length > 1) usage('Error: prune takes at most one path argument')
+  const root = argv[0] ? resolve(argv[0]) : process.cwd()
+  const { prune } = await import('../src/prune.js')
+  const { removed, validated } = prune({ root })
+  console.warn(`[stasis] prune: validated ${validated.length} file(s), removed ${removed.length} file(s)`)
+} else if (command === 'audit') {
+  if (argv.length === 0) usage('Nothing to audit: no path to file given')
+  const { audit, printAuditReport } = await import('../src/audit.js')
+  const files = argv.map((f) => resolve(f))
+  const report = await audit(files)
+  printAuditReport(report)
+  process.exitCode = report.rows.length === 0 ? 0 : 1
+} else {
+  usage()
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@exodus/stasis",
+  "version": "1.0.0-alpha.1",
+  "description": "A research project",
+  "type": "module",
+  "exports": {
+    "./esbuild": "./src/esbuild.js",
+    "./webpack": "./src/webpack.js",
+    "./loader": "./src/loader.js",
+    "./bundle": "./src/bundle.js",
+    "./lockfile": "./src/lockfile.js",
+    "./prune": "./src/prune.js"
+  },
+  "files": [
+    "bin/stasis.js",
+    "src/apis/npm/index.js",
+    "src/apis/npm/semver.cjs",
+    "src/bundle.js",
+    "src/config.js",
+    "src/esbuild.js",
+    "src/loader.js",
+    "src/lockfile.js",
+    "src/prune.js",
+    "src/state.js",
+    "src/state.util.js",
+    "src/util.js",
+    "src/webpack.js"
+  ],
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "bin": {
+    "stasis": "bin/stasis.js"
+  },
+  "scripts": {
+    "lint": "oxlint",
+    "test": "node --run test:coherence",
+    "test:coherence": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExodusMovement/stasis.git"
+  },
+  "author": "Exodus Movement, Inc.",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ExodusMovement/stasis/issues"
+  },
+  "homepage": "https://github.com/ExodusMovement/stasis#readme",
+  "devDependencies": {
+    "@exodus/bytes": "^1.15.0",
+    "esbuild": "^0.27.3",
+    "oxlint": "^1.52.0",
+    "string-replace-loader": "^2.3.0",
+    "webpack": "^4.47.0"
+  },
+  "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800"
+}

package/src/apis/npm/index.js

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict'
+
+import semver from './semver.cjs'
+
+const packageNameRegex = /^(@[\da-z-]+\/)?[\w-]+(\.[\w-]+)*$/u
+
+export async function advisories(list, { signal = AbortSignal.timeout(30_000) } = {}) {
+  const groups = new Map()
+  for (const { name, version } of list) {
+    assert(typeof name === 'string' && typeof version === 'string')
+    assert(packageNameRegex.test(name), `Unexpected package name: ${name}`)
+    assert(semver.valid(version), `Invalid version: ${version}`)
+    if (!groups.has(name)) groups.set(name, new Set())
+    groups.get(name).add(version)
+  }
+
+  const entries = [...groups].map(([k, v]) => [k, [...v].toSorted((a, b) => semver.compare(a, b))])
+  const body = Object.fromEntries(entries.toSorted((a, b) => a[0] < b[0] ? -1 : 1))
+
+  let res
+  try {
+    res = await fetch('https://registry.npmjs.org/-/npm/v1/security/advisories/bulk', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal,
+    })
+  } catch (cause) {
+    throw new Error(`npm advisories request failed: ${cause.message}`, { cause })
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    throw new Error(`npm advisories request failed: ${res.status} ${res.statusText}${text ? ` — ${text.slice(0, 200)}` : ''}`)
+  }
+  return res.json()
+}

package/src/apis/npm/semver.cjs

@@ -0,0 +1,44 @@
+'use strict'
+
+const assert = require('node:assert/strict')
+const { basename, dirname, resolve } = require('node:path')
+
+let semver
+
+const argv0 = process.argv[0] // not process.argv0 which lacks path
+
+function getSemver() {
+  if (semver) return semver
+
+  // Coherence check that we got Node.js path there
+  assert(['node', 'node.exe'].includes(basename(argv0)))
+  assert.equal(basename(argv0), basename(process.argv0))
+
+  // Load semver from npm bundled with Node.js
+  const semverDir = resolve(dirname(argv0), '../lib/node_modules/npm/node_modules/semver')
+  semver = require(semverDir)
+  return semver
+}
+
+exports.compare = (...a) => getSemver().compare(...a)
+exports.gtr = (...a) => getSemver().gtr(...a)
+exports.lt = (...a) => getSemver().lt(...a)
+exports.lte = (...a) => getSemver().lte(...a)
+exports.ltr = (...a) => getSemver().ltr(...a)
+exports.satisfies = (...a) => getSemver().satisfies(...a)
+exports.validRange = (...a) => getSemver().validRange(...a)
+
+exports.valid = (version, options) => {
+  // Fast path for certainly valid versions
+  if (
+    options === undefined &&
+    typeof version === 'string' &&
+    version.length <= 256 &&
+    // 1-15 chars because it must fit in Number.MAX_SAFE_INTEGER
+    /^(0|[1-9]\d{0,14})\.(0|[1-9]\d{0,14})\.(0|[1-9]\d{0,14})$/iu.test(version)
+  ) {
+    return version
+  }
+
+  return getSemver().valid(version, options)
+}

package/src/bundle.js

@@ -0,0 +1,217 @@
+import {
+  assert,
+  fileMapToObject,
+  fileSetToObject,
+  fromEntries,
+  objectToMaps,
+  sortPaths,
+  splitNodeModulesPath,
+} from './util.js'
+
+const VERSION = 1
+const LEGACY_VERSION = 0
+
+const normalize = ({ name, version, files }) =>
+  ({ name, version, files: fromEntries(Object.entries(files)) })
+
+const inferModuleDir = (path) =>
+  splitNodeModulesPath(path) ?? { dir: '.', rel: path, name: null }
+
+// Bundle handles the JSON shape of stasis.code.br / stasis.resources.br;
+// callers (State) are responsible for the brotli wrapper around the JSON
+// text. On-disk version:
+//   v0 — legacy flat layout: top-level `sources` (or `resources`) keyed by
+//        project-relative path. No entries/modules metadata.
+//   v1 — current layout, mirrors stasis.lock.json: per-package buckets under
+//        `sources` (workspace) and `modules` (node_modules) with name+version+files,
+//        plus `entries`. File payloads carry bytes (UTF-8 source strings or base64
+//        resource blobs) instead of SRI digests.
+// We load both v0 and v1; we always serialize v1. v0 is converted on load to
+// the same in-memory shape — paths are regrouped by package dir via
+// `inferModuleDir` (best-effort, last-wins). name/version stay null since v0
+// records neither, which State uses as a marker to skip metadata cross-checks.
+export class Bundle {
+  static VERSION = VERSION
+
+  // The on-disk version this instance represents. Defaults to VERSION; parse*
+  // sets it to whatever the file declared (LEGACY_VERSION for v0 input).
+  // Serialization always writes the current VERSION regardless — loading v0 and
+  // re-saving promotes the bundle to v1.
+  version = VERSION
+  config
+  entries
+  modules
+  formats
+  imports
+
+  constructor({ config = { scope: 'full' }, entries, modules, formats, imports, version = VERSION } = {}) {
+    assert([LEGACY_VERSION, VERSION].includes(version))
+    assert(['node_modules', 'full'].includes(config.scope))
+    this.version = version
+    this.config = config
+    this.entries = entries ?? new Set()
+    this.modules = modules ?? new Map()
+    this.formats = formats ?? new Map()
+    this.imports = imports ?? new Map()
+  }
+
+  // Flat project-relative view of file contents collected from this.modules.
+  // Values are UTF-8 source strings for code bundles, base64 for resource bundles.
+  get sources() {
+    const m = new Map()
+    for (const [dir, { files }] of this.modules) {
+      for (const [rel, content] of Object.entries(files)) {
+        m.set(dir === '.' ? rel : `${dir}/${rel}`, content)
+      }
+    }
+    return m
+  }
+
+  static parseCode(text) {
+    const json = JSON.parse(text)
+    assert(json.version === VERSION || json.version === LEGACY_VERSION)
+    assert(['node_modules', 'full'].includes(json.config?.scope))
+    assert(json.formats)
+    assert(json.imports)
+
+    const modules = new Map()
+    let entries = new Set()
+
+    if (json.version === VERSION) {
+      const full = json.config.scope === 'full'
+      if (json.modules !== undefined) {
+        assert(typeof json.modules === 'object' && json.modules !== null)
+        for (const [dir, info] of Object.entries(json.modules)) {
+          assert(dir.includes('node_modules'))
+          assert(!dir.startsWith('..'))
+          assert(info?.name && info.version && info.files)
+          modules.set(dir, normalize(info))
+        }
+      }
+      if (full) {
+        assert(Array.isArray(json.entries))
+        // Empty entries in v1 + full would let `state.assertEntry` skip its check
+        // (it short-circuits on entries.size === 0 for v0+no-lockfile compatibility).
+        // Forbid the shape at parse time so tampered bundles can't exploit that path.
+        assert(json.entries.length > 0, 'v1 bundle with scope=full must have at least one entry')
+        assert(json.sources && typeof json.sources === 'object')
+        entries = new Set(json.entries)
+        for (const [dir, info] of Object.entries(json.sources)) {
+          assert(!dir.includes('node_modules'))
+          assert(!dir.startsWith('..'))
+          assert(info?.name && info.version && info.files)
+          modules.set(dir, normalize(info))
+        }
+      } else {
+        assert(json.entries === undefined)
+        assert(json.sources === undefined)
+      }
+      for (const [, { files }] of modules) {
+        for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
+      }
+    } else {
+      // v0 legacy: flat sources at top level, regrouped by inferred module dir.
+      assert(json.sources)
+      for (const [path, content] of Object.entries(json.sources)) {
+        assert(!path.startsWith('..'))
+        const { dir, rel, name } = inferModuleDir(path)
+        assert(!dir.startsWith('..') && !rel.startsWith('..'))
+        if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
+        modules.get(dir).files[rel] = content
+      }
+    }
+
+    return new Bundle({
+      version: json.version,
+      config: json.config,
+      entries,
+      modules,
+      formats: new Map(Object.entries(json.formats)),
+      imports: objectToMaps(json.imports),
+    })
+  }
+
+  static parseResources(text) {
+    const json = JSON.parse(text)
+    assert(json.version === VERSION || json.version === LEGACY_VERSION)
+
+    const modules = new Map()
+    let config = { scope: 'full' }
+
+    if (json.version === VERSION) {
+      assert(['node_modules', 'full'].includes(json.config?.scope))
+      config = json.config
+      const full = config.scope === 'full'
+      if (json.modules !== undefined) {
+        assert(typeof json.modules === 'object' && json.modules !== null)
+        for (const [dir, info] of Object.entries(json.modules)) {
+          assert(dir.includes('node_modules'))
+          assert(!dir.startsWith('..'))
+          assert(info?.name && info.version && info.files)
+          modules.set(dir, normalize(info))
+        }
+      }
+      if (full && json.sources !== undefined) {
+        assert(typeof json.sources === 'object' && json.sources !== null)
+        for (const [dir, info] of Object.entries(json.sources)) {
+          assert(!dir.includes('node_modules'))
+          assert(!dir.startsWith('..'))
+          assert(info?.name && info.version && info.files)
+          modules.set(dir, normalize(info))
+        }
+      } else if (!full) {
+        assert(json.sources === undefined)
+      }
+      for (const [, { files }] of modules) {
+        for (const rel of Object.keys(files)) assert(!rel.startsWith('..'))
+      }
+    } else {
+      // v0 legacy: flat resources at top level, regrouped by inferred module dir.
+      assert(json.resources)
+      for (const [path, content] of Object.entries(json.resources)) {
+        assert(!path.startsWith('..'))
+        const { dir, rel, name } = inferModuleDir(path)
+        assert(!dir.startsWith('..') && !rel.startsWith('..'))
+        if (!modules.has(dir)) modules.set(dir, { name, version: null, files: Object.create(null) })
+        modules.get(dir).files[rel] = content
+      }
+    }
+
+    return new Bundle({ version: json.version, config, modules })
+  }
+
+  #groupedFromModules() {
+    const moduleEntries = []
+    const sourceEntries = []
+    for (const [dir, { name, version, files }] of this.modules) {
+      if (Object.keys(files).length === 0) continue
+      const inNodeModules = dir.includes('node_modules')
+      if (inNodeModules) assert(name && version && files)
+      const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
+      const target = inNodeModules ? moduleEntries : sourceEntries
+      target.push([dir, { name, version, files: sorted }])
+    }
+    moduleEntries.sort((a, b) => sortPaths(a[0], b[0]))
+    sourceEntries.sort((a, b) => sortPaths(a[0], b[0]))
+    return { modules: fromEntries(moduleEntries), sources: fromEntries(sourceEntries) }
+  }
+
+  serializeCode() {
+    const entries = fileSetToObject(this.entries)
+    const { modules, sources } = this.#groupedFromModules()
+    const formats = fileMapToObject(this.formats)
+    const imports = fileMapToObject(this.imports)
+    const data = { version: VERSION, config: this.config }
+    if (this.config.scope === 'full') Object.assign(data, { entries, sources })
+    Object.assign(data, { modules, formats, imports })
+    return JSON.stringify(data, undefined, 2)
+  }
+
+  serializeResources() {
+    const { modules, sources } = this.#groupedFromModules()
+    const data = { version: VERSION, config: this.config }
+    if (this.config.scope === 'full') Object.assign(data, { sources })
+    Object.assign(data, { modules })
+    return JSON.stringify(data, undefined, 2)
+  }
+}