@exodus/stasis 1.0.0-alpha.1

package/src/config.js

@@ -0,0 +1,205 @@
+import assert from 'node:assert/strict'
+
+const VALID_SCOPE = new Set(['node_modules', 'full'])
+const VALID_LOCK = new Set(['none', 'ignore', 'add', 'replace', 'frozen'])
+const VALID_BUNDLE = new Set(['none', 'ignore', 'add', 'replace', 'load'])
+
+const envDebugBool = (value) => Boolean(value && value !== '0')
+
+const OPTION_KEYS = ['scope', 'lock', 'bundle', 'bundleFile', 'debug']
+
+// Plugins accept the same options as Config but want to validate without constructing one,
+// since constructing State has side effects. Mirror Config's per-field validation.
+export function validatePluginOptions(label, options) {
+  const rest = { ...options }
+  for (const key of OPTION_KEYS) delete rest[key]
+  assert.equal(Object.keys(rest).length, 0, `Unknown ${label} options: ${Object.keys(rest).join(', ')}`)
+  const { scope, lock, bundle, bundleFile, debug } = options
+  if (scope !== undefined) assert.ok(VALID_SCOPE.has(scope), `Invalid scope: ${scope}`)
+  if (lock !== undefined) assert.ok(VALID_LOCK.has(lock), `Invalid lock: ${lock}`)
+  if (bundle !== undefined) assert.ok(VALID_BUNDLE.has(bundle), `Invalid bundle: ${bundle}`)
+  if (bundleFile !== undefined) assert.equal(typeof bundleFile, 'string', 'bundleFile must be a string')
+  if (debug !== undefined) assert.equal(typeof debug, 'boolean', 'debug must be a boolean')
+}
+
+// When a plugin runs against a State that already exists (preload path), the active Config
+// is authoritative. Any options the plugin was given must agree with it.
+export function assertOptionsMatchConfig(config, options) {
+  const { scope, lock, bundle, bundleFile, debug } = options
+  try {
+    if (scope !== undefined) assert.equal(config.scope, scope)
+    if (lock !== undefined) assert.equal(config.lock, lock)
+    if (bundle !== undefined) assert.equal(config.bundleMode, bundle)
+    if (bundleFile !== undefined) assert.equal(config.bundleFile, bundleFile)
+    if (debug !== undefined) assert.equal(config.debug, debug)
+  } catch (cause) {
+    throw new Error('Plugin options conflict with active stasis state', { cause })
+  }
+}
+
+export class Config {
+  #env
+  #scope
+  #lock
+  #bundle
+  #bundleFile
+  #debug
+
+  // Options match the CLI flags (lock/bundle/bundleFile/scope/debug). Env vars take effect at
+  // construction time; if both env and an option are set they must agree.
+  constructor(options = {}) {
+    const { scope, lock, bundle, bundleFile, debug, ...rest } = options
+    assert.equal(Object.keys(rest).length, 0, `Unknown Config options: ${Object.keys(rest).join(', ')}`)
+
+    this.#env = {
+      scope: process.env.EXODUS_STASIS_SCOPE || undefined,
+      lock: process.env.EXODUS_STASIS_LOCK || undefined,
+      bundle: process.env.EXODUS_STASIS_BUNDLE || undefined,
+      bundleFile: process.env.EXODUS_STASIS_BUNDLE_FILE || undefined,
+      debug: process.env.EXODUS_STASIS_DEBUG || undefined,
+    }
+
+    try {
+      if (this.#env.scope !== undefined && scope !== undefined) assert.equal(this.#env.scope, scope)
+      if (this.#env.lock !== undefined && lock !== undefined) assert.equal(this.#env.lock, lock)
+      if (this.#env.bundle !== undefined && bundle !== undefined) assert.equal(this.#env.bundle, bundle)
+      if (this.#env.bundleFile !== undefined && bundleFile !== undefined) {
+        assert.equal(this.#env.bundleFile, bundleFile)
+      }
+      if (this.#env.debug !== undefined && debug !== undefined) {
+        assert.equal(envDebugBool(this.#env.debug), debug)
+      }
+    } catch (cause) {
+      throw new Error('Config options can not override stasis env', { cause })
+    }
+
+    this.#scope = this.#env.scope || scope || 'full'
+    this.#lock = this.#env.lock || lock || 'add'
+    this.#bundle = this.#env.bundle || bundle || 'none'
+    this.#bundleFile = this.#env.bundleFile || bundleFile || undefined
+    this.#debug = this.#env.debug !== undefined ? envDebugBool(this.#env.debug) : (debug ?? false)
+
+    this.#checkInvariants()
+  }
+
+  // Per-field validation + cross-field invariants. Constructor (options path) and
+  // loadConfig (disk path) both call this so the rules live in one place.
+  #checkInvariants() {
+    assert.ok(VALID_SCOPE.has(this.#scope), `Invalid scope: ${this.#scope}`)
+    assert.ok(VALID_LOCK.has(this.#lock), `Invalid lock: ${this.#lock}`)
+    assert.ok(VALID_BUNDLE.has(this.#bundle), `Invalid bundle: ${this.#bundle}`)
+    assert.equal(typeof this.#debug, 'boolean', 'debug must be a boolean')
+    if (this.#bundleFile !== undefined) assert.equal(typeof this.#bundleFile, 'string', 'bundleFile must be a string')
+
+    // bundle=load needs a trust root for source bytes: frozen pins each file's sha512 in
+    // the lockfile and we cross-check it on load; otherwise the bundle is itself
+    // authoritative -- lock=none with no lockfile on disk, or lock=ignore with a lockfile
+    // deliberately bypassed.
+    // WARNING: lockfile attests only to source BYTES, not bundle metadata.
+    if (this.#bundle === 'load' && this.#lock !== 'frozen' && this.#lock !== 'none' && this.#lock !== 'ignore') {
+      throw new RangeError('bundle=load requires lock=(frozen|none|ignore)')
+    }
+
+    if (this.#lock === 'none' && this.#bundle === 'none') {
+      throw new RangeError('lock=none requires bundle=(add|replace|load|ignore)')
+    }
+  }
+
+  loadConfig(json) {
+    const {
+      scope = this.#scope,
+      lock = this.#lock,
+      bundle = this.#bundle,
+      debug = this.#debug,
+      ...rest
+    } = JSON.parse(json)
+    assert.equal(Object.keys(rest).length, 0)
+    this.#scope = scope
+    this.#lock = lock
+    this.#bundle = bundle
+    this.#debug = debug
+    this.#checkInvariants()
+
+    try {
+      if (this.#env.scope !== undefined) assert.equal(this.#scope, this.#env.scope)
+      if (this.#env.lock !== undefined) assert.equal(this.#lock, this.#env.lock)
+      if (this.#env.bundle !== undefined) assert.equal(this.#bundle, this.#env.bundle)
+      if (this.#env.debug !== undefined) assert.equal(this.#debug, envDebugBool(this.#env.debug))
+    } catch (cause) {
+      throw new Error('Flags/env can not override stasis.config.json', { cause })
+    }
+  }
+
+  get bundleFile() {
+    return this.#bundleFile
+  }
+
+  get debug() {
+    return this.#debug
+  }
+
+  get values() {
+    return { scope: this.#scope }
+  }
+
+  get bundle() {
+    return this.#bundle !== 'none' && this.#bundle !== 'ignore'
+  }
+
+  get bundleMode() {
+    return this.#bundle
+  }
+
+  get ignoreBundle() {
+    return this.#bundle === 'ignore'
+  }
+
+  get writeBundle() {
+    return this.#bundle === 'add' || this.#bundle === 'replace'
+  }
+
+  get replaceBundle() {
+    return this.#bundle === 'replace'
+  }
+
+  get loadBundle() {
+    return this.#bundle === 'load'
+  }
+
+  get full() {
+    return this.#scope === 'full'
+  }
+
+  get frozen() {
+    return this.#lock === 'frozen'
+  }
+
+  get useLockfile() {
+    return this.#lock !== 'none' && this.#lock !== 'ignore'
+  }
+
+  get ignoreLockfile() {
+    return this.#lock === 'ignore'
+  }
+
+  get writeLockfile() {
+    return this.#lock === 'add' || this.#lock === 'replace'
+  }
+
+  get replaceLockfile() {
+    return this.#lock === 'replace'
+  }
+
+  get scope() {
+    return this.#scope
+  }
+
+  get lock() {
+    return this.#lock
+  }
+
+  get json() {
+    const data = { scope: this.#scope, lock: this.#lock, bundle: this.#bundle }
+    return JSON.stringify(data, undefined, 2) + '\n'
+  }
+}

package/src/esbuild.js

@@ -0,0 +1,56 @@
+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 }
+    })
+  }
+}

package/src/loader.js

@@ -0,0 +1,132 @@
+import { registerHooks, findPackageJSON, isBuiltin } from 'node:module'
+import { basename, dirname, extname, resolve as resolvePath } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import assert from 'node:assert/strict'
+
+import { State } from './state.js'
+
+// Warning: only covers code imports, not file reads
+
+let state
+let saved = false
+
+function initState(root) {
+  state = new State(root, { preload: true })
+
+  const save = () => {
+    if (saved) return
+    saved = true
+    state.write()
+  }
+
+  process.on('beforeExit', save)
+  process.on('exit', save)
+}
+
+function load(url, context, nextLoad) {
+  assert.equal(typeof url, 'string')
+
+  if (url.startsWith('node:')) {
+    const result = nextLoad(url, context)
+    assert.equal(result.format, 'builtin')
+    return result
+  }
+
+  if (state && state.config.loadBundle) {
+    // node_modules scope only bundles node_modules sources; non-tracked files are read
+    // from disk through Node's default loader (state.getFile is never called for them).
+    if (!state.config.full && !url.includes('/node_modules/')) {
+      return nextLoad(url, context)
+    }
+    const { source, format } = state.getFile(url)
+    // context.format may be null when the resolve chain didn't set it (e.g. node_modules
+    // scope, where non-nm parents go through nextResolve and Node's default doesn't
+    // populate format for the load hook). Only cross-check when the chain provided one.
+    // TODO: format here is sourced from the bundle's `formats` map, which the lockfile
+    // does not currently cover; a tampered bundle can flip module<->commonjs for a
+    // hash-valid file. Derive format from extension + module.type (recorded in the
+    // lockfile) and reject the bundle's claim when it disagrees.
+    if (context.format != null) assert.equal(format, context.format)
+    assert.ok(['module', 'commonjs', 'json'].includes(format))
+    return { source, format, shortCircuit: true }
+  }
+
+  const result = nextLoad(url, context)
+  let { source } = result
+  const { format } = result
+  assert.notEqual(format, 'builtin')
+
+  // Node's CJS loader may return source=null and read from disk itself; capture it for the bundle
+  if (source == null && format === 'commonjs') source = readFileSync(fileURLToPath(url))
+
+  const isEntry = !state
+  if (!state) {
+    const pkg = findPackageJSON(url)
+    assert.equal(basename(pkg), 'package.json')
+    initState(dirname(pkg))
+  }
+
+  assert.equal(saved, false)
+  state.addFile(url, { source, format, isEntry })
+
+  return result
+}
+
+function resolve(specifier, context, nextResolve) {
+  if (isBuiltin(specifier)) {
+    const res = nextResolve(specifier)
+    assert.equal(res.url, specifier.startsWith('node:') ? specifier : `node:${specifier}`)
+    return res
+  }
+
+  if (context.importAttributes !== undefined) {
+    const expectedAttrs = Object.create(null) // Saving is not supported yet, so we ensure expected ones
+    if (extname(specifier) === '.json' && context.importAttributes?.type) expectedAttrs.type = 'json'
+    assert.deepStrictEqual(context.importAttributes, expectedAttrs)
+  }
+
+  const { parentURL, conditions, importAttributes } = context
+
+  // In full-scope load mode, the entry point is served from the bundle without touching
+  // disk, so state must be initialised before nextResolve runs. node_modules scope reads
+  // non-nm sources (including the entry) from disk, so state is initialised later in load().
+  if (!state && !parentURL && process.env.EXODUS_STASIS_BUNDLE === 'load'
+      && process.env.EXODUS_STASIS_SCOPE !== 'node_modules') {
+    initState(process.cwd())
+  }
+
+  if (state && state.config.loadBundle) {
+    // node_modules scope defers resolution of non-nm parents to Node. Relative imports
+    // between non-nm sources then resolve to local files, and bare specifiers resolve via
+    // the on-disk node_modules layout -- but the load() hook still serves the resulting
+    // node_modules target from the bundle, so package contents need not be on disk.
+    if (!state.config.full && !parentURL?.includes('/node_modules/')) {
+      return nextResolve(specifier)
+    }
+    // Bare specifier with a parent is the regular ESM import: look up the recorded
+    // import map. Otherwise we have either a pre-resolved file URL (CLI entries and
+    // ESM-to-CJS translator require() targets both arrive that way) or a bare entry
+    // specifier we anchor to cwd -- either way, skip nextResolve so the entry file
+    // doesn't need to exist on disk.
+    if (parentURL && !specifier.startsWith('file:')) {
+      const { url, format } = state.getImport(parentURL, specifier, { conditions, importAttributes })
+      return { url, format, importAttributes: undefined, shortCircuit: true }
+    }
+    const url = specifier.startsWith('file:')
+      ? specifier
+      : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
+    if (!parentURL && state.config.full) state.assertEntry(url)
+    return { url, format: state.getFormat(url), importAttributes: undefined, shortCircuit: true }
+  }
+
+  const res = nextResolve(specifier)
+  const { url, format } = res
+
+  assert.equal(res.importAttributes, undefined) // unsupported yet
+  if (parentURL) assert.ok(state)
+  if (state) state.addImport(parentURL, specifier, url, { conditions, format, importAttributes })
+  return res
+}
+
+registerHooks({ load, resolve })

package/src/lockfile.js

@@ -0,0 +1,80 @@
+import { assert, fileSetToObject, fromEntries, sortPaths } from './util.js'
+
+const VERSION = 0
+
+const normalize = ({ name, version, files }) =>
+  ({ name, version, files: fromEntries(Object.entries(files)) })
+
+export class Lockfile {
+  static VERSION = VERSION
+
+  version = VERSION
+  config
+  entries
+  modules
+
+  constructor({ config = { scope: 'full' }, entries, modules } = {}) {
+    assert(['node_modules', 'full'].includes(config.scope))
+    this.config = config
+    this.entries = entries ?? new Set()
+    this.modules = modules ?? new Map()
+  }
+
+  static parse(text) {
+    const json = JSON.parse(text)
+    assert(json.version === VERSION)
+    assert(['node_modules', 'full'].includes(json.config?.scope))
+
+    const full = json.config.scope === 'full'
+    assert(!!json.entries === full)
+    assert(!!json.sources === full)
+    assert(json.modules)
+
+    const modules = new Map()
+    for (const [dir, info] of Object.entries(json.modules)) {
+      assert(dir.includes('node_modules'))
+      assert(info?.name && info.version && info.files)
+      modules.set(dir, normalize(info))
+    }
+
+    let entries = new Set()
+    if (full) {
+      assert(Array.isArray(json.entries))
+      entries = new Set(json.entries)
+      for (const [dir, info] of Object.entries(json.sources)) {
+        assert(!dir.includes('node_modules'))
+        modules.set(dir, normalize(info))
+      }
+    }
+
+    for (const [dir, { files }] of modules) {
+      assert(!dir.startsWith('..'))
+      assert(files)
+      for (const name of Object.keys(files)) {
+        assert(!name.startsWith('..'))
+      }
+    }
+
+    return new Lockfile({ config: json.config, entries, modules })
+  }
+
+  serialize() {
+    const entries = fileSetToObject(this.entries)
+    const modules = []
+    const sources = []
+    for (const [dir, { name, version, files }] of this.modules) {
+      const inNodeModules = dir.includes('node_modules')
+      if (inNodeModules) assert(name && version && files)
+      const type = inNodeModules ? modules : sources
+      const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
+      type.push([dir, { name, version, files: sorted }])
+    }
+    modules.sort((a, b) => sortPaths(a[0], b[0]))
+    sources.sort((a, b) => sortPaths(a[0], b[0]))
+
+    const store = { version: this.version, config: this.config }
+    if (this.config.scope === 'full') Object.assign(store, { entries, sources: fromEntries(sources) })
+    Object.assign(store, { modules: fromEntries(modules) })
+    return JSON.stringify(store, undefined, 2) + '\n'
+  }
+}

package/src/prune.js

@@ -0,0 +1,162 @@
+import assert from 'node:assert/strict'
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  rmdirSync,
+  unlinkSync,
+} from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+
+import { Lockfile } from './lockfile.js'
+import { sha512integrity } from './state.util.js' // also runs the posix-sep assertion
+
+const LOCKFILE = 'stasis.lock.json'
+
+function assertGlobalVirtualStoreDisabled() {
+  // pnpm exports its settings as `npm_config_*` env vars to hooks and
+  // lifecycle scripts. When the global virtual store is enabled, node_modules
+  // is dominated by symlinks into a shared store; pruning would walk past
+  // most files (we skip symlinks) and the lockfile-vs-disk comparison stops
+  // being meaningful. Reject before touching anything.
+  const env = process.env.npm_config_enable_global_virtual_store
+  if (env !== undefined && env !== 'false' && env !== '') {
+    throw new Error(
+      `stasis prune: enableGlobalVirtualStore must be false, got ${JSON.stringify(env)}`,
+    )
+  }
+}
+
+function loadLockfile(root) {
+  const path = join(root, LOCKFILE)
+  assert.ok(existsSync(path), `stasis prune: ${LOCKFILE} not found at ${path}`)
+  return Lockfile.parse(readFileSync(path, 'utf8'))
+}
+
+function buildExpected(lockfile) {
+  const expected = new Map()
+  const knownDirs = new Set()
+  for (const [dir, { files }] of lockfile.modules) {
+    if (!dir.includes('node_modules')) continue // workspace sources, not pnpm-managed
+    knownDirs.add(dir)
+    for (const [rel, hash] of Object.entries(files)) {
+      expected.set(`${dir}/${rel}`, hash)
+    }
+  }
+  return { expected, knownDirs }
+}
+
+function* walkFiles(nodeModules) {
+  if (!existsSync(nodeModules)) return
+  const stack = [nodeModules]
+  while (stack.length > 0) {
+    const dir = stack.pop()
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name)
+      // Skip symlinks: pnpm's flat node_modules symlinks into .pnpm; the file
+      // bytes are reachable via the symlink targets which we also walk
+      // directly when we descend into .pnpm.
+      if (entry.isSymbolicLink()) continue
+      if (entry.isDirectory()) stack.push(full)
+      else if (entry.isFile()) yield full
+    }
+  }
+}
+
+function pruneEmptyDirs(dir, stopAt) {
+  while (dir.startsWith(stopAt) && dir !== stopAt && existsSync(dir)) {
+    let entries
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    if (entries.length > 0) return
+    try {
+      rmdirSync(dir)
+    } catch {
+      return
+    }
+    dir = dirname(dir)
+  }
+}
+
+export function prune({ root = process.cwd() } = {}) {
+  assertGlobalVirtualStoreDisabled()
+  root = resolve(root)
+  const nodeModules = join(root, 'node_modules')
+  const lockfile = loadLockfile(root)
+  const { expected, knownDirs } = buildExpected(lockfile)
+
+  // Plan first, mutate later: walk the tree, validate every tracked file,
+  // collect the deletion list, and verify nothing in the lockfile is
+  // missing. Bail with a thrown error before touching disk on any failure.
+  const toRemove = []
+  const validated = []
+  const kept = []
+  const seen = new Set()
+  const mismatches = []
+
+  for (const full of walkFiles(nodeModules)) {
+    const rel = relative(root, full)
+    const expectedHash = expected.get(rel)
+    if (expectedHash !== undefined) {
+      seen.add(rel)
+      const actual = sha512integrity(readFileSync(full))
+      if (actual === expectedHash) {
+        validated.push(rel)
+        kept.push(rel)
+      } else {
+        mismatches.push({ rel, expected: expectedHash, actual })
+      }
+      continue
+    }
+
+    // Package.json files are kept (without hash validation, since they may
+    // not be enumerated in the lockfile) only when their containing dir is
+    // a module recorded in the lockfile. Stray package.jsons under
+    // node_modules dirs that the lockfile doesn't know about get pruned
+    // along with the rest of those modules.
+    if (basename(rel) === 'package.json' && knownDirs.has(dirname(rel))) {
+      kept.push(rel)
+      continue
+    }
+
+    // Defense-in-depth: the path must resolve inside node_modules (no
+    // symlink escape, no `..` traversal) before we queue it for deletion.
+    assert.ok(
+      full === nodeModules || full.startsWith(`${nodeModules}${sep}`),
+      `refusing to remove path outside node_modules: ${full}`,
+    )
+    toRemove.push(full)
+  }
+
+  const missing = []
+  for (const [rel] of expected) {
+    if (!seen.has(rel)) missing.push(rel)
+  }
+
+  if (mismatches.length > 0) {
+    const lines = mismatches.map(({ rel, expected: exp, actual }) =>
+      `  ${rel}: expected ${exp}, got ${actual}`).join('\n')
+    throw new Error(`stasis prune: hash mismatch for ${mismatches.length} file(s):\n${lines}`)
+  }
+  if (missing.length > 0) {
+    const sample = missing.slice(0, 5).join(', ')
+    const suffix = missing.length > 5 ? `, ... (${missing.length} total)` : ''
+    throw new Error(`stasis prune: files listed in lockfile are missing on disk: ${sample}${suffix}`)
+  }
+
+  const removed = []
+  const touchedDirs = new Set()
+  for (const full of toRemove) {
+    unlinkSync(full)
+    removed.push(relative(root, full))
+    touchedDirs.add(dirname(full))
+  }
+
+  const sortedDirs = [...touchedDirs].toSorted((a, b) => b.length - a.length)
+  for (const d of sortedDirs) pruneEmptyDirs(d, nodeModules)
+
+  return { removed, validated, kept }
+}