@exodus/stasis 1.0.0-beta.0 → 1.0.0-beta.10

package/src/installed-commits.js

@@ -0,0 +1,182 @@
+import { hash } from 'node:crypto'
+import { dirname, join, relative, resolve } from 'node:path'
+
+import { toBase32 } from '@exodus/bytes/base32.js'
+import { isValidRepoField } from '@exodus/stasis-core/bundle'
+import { parseGithubRepository, readJson, readText } from '@exodus/stasis-core/bundle-util'
+import { diskHost } from '@exodus/stasis-core/host'
+import { isPlainObject, relativeEscapes, toPosix } from '@exodus/stasis-core/util'
+import { parsePnpmLockfile } from '@preventive/lockfile/pnpm.js'
+import { parseYarn1Lockfile } from '@preventive/lockfile/yarn1.js'
+
+// The commit each git dependency in a node_modules on disk is installed at, as the package manager
+// that laid it out recorded it there: npm in its hidden lockfile, pnpm in its copy of the lockfile,
+// yarn 1 in yarn.lock, as its .yarn-integrity has it installed. Nothing on disk names a registry
+// package's. A record missing, unreadable, or naming no full commit of a GitHub repository records
+// nothing, and fails nothing.
+
+// `{ github, commit }` of `repo`, a git URL, at `commit`, where that is a GitHub repository and a full
+// commit id; else undefined.
+function githubCommit(repo, commit) {
+  const github = parseGithubRepository(repo)
+  return github !== null && isValidRepoField('commit', commit) ? { github, commit } : undefined
+}
+
+// GitHub's tarball of a commit, as yarn 1 and pnpm fetch a GitHub dependency.
+const CODELOAD = /^https:\/\/codeload\.github\.com\/([^/]+\/[^/]+)\/tar\.gz\/([^/]+)$/u
+const githubTarball = (url) => {
+  const [, github, commit] = CODELOAD.exec(url) ?? []
+  return isValidRepoField('github', github) ? githubCommit(github, commit) : undefined
+}
+
+// githubCommit of a git or tarball resolution @preventive/lockfile reads.
+const resolutionCommit = (resolution) => {
+  if (resolution?.type === 'git') return githubCommit(resolution.repo, resolution.commit)
+  return resolution?.type === 'tarball' ? githubTarball(resolution.tarball ?? '') : undefined
+}
+
+// The lookup of a record that finds nothing: one unreadable, or none.
+const NONE = () => undefined
+
+// npm's, from npm 7: the hidden lockfile it writes into `dir`'s node_modules as it lays it out, by
+// each package's location from `dir`, where it records the version installed there. A git
+// dependency's `resolved` is the URL npm clones, `#` and the commit.
+function npmRecord(dir, host) {
+  const packages = readJson(join(dir, 'node_modules', '.package-lock.json'), host)?.packages
+  if (!isPlainObject(packages)) return NONE
+  return (location, version) => {
+    const entry = Object.hasOwn(packages, location) ? packages[location] : undefined
+    if (!isPlainObject(entry) || entry.version !== version || typeof entry.resolved !== 'string') return undefined
+    const { resolved } = entry
+    if (!/^git(?:\+[\w.-]+)?:/u.test(resolved)) return githubTarball(resolved)
+    const at = resolved.lastIndexOf('#')
+    return at === -1 ? undefined : githubCommit(resolved.slice(0, at), resolved.slice(at + 1))
+  }
+}
+
+// yarn 1's: yarn.lock in `dir`, by the name a package is installed as, the last of its location, and
+// its version, where one entry alone has both. The .yarn-integrity yarn writes into the node_modules
+// it lays out has to hold the entry's resolution for each of its patterns, as yarn.lock's `resolved`
+// spells it: a yarn.lock changed since often moves a git dependency to another commit of one version.
+function yarnRecord(dir, host) {
+  const installed = readJson(join(dir, 'node_modules', '.yarn-integrity'), host)?.lockfileEntries
+  const text = readText(host, join(dir, 'yarn.lock'))
+  if (!isPlainObject(installed) || text === null) return NONE
+  let packages
+  try {
+    packages = parseYarn1Lockfile(text, { checkVersions: false }).packages
+  } catch {
+    return NONE // whatever the reader refuses
+  }
+  const byVersion = new Map()
+  for (const { patterns, name, version, resolution } of new Set(Object.values(packages))) {
+    let commit = resolutionCommit(resolution)
+    const resolved = resolution?.type === 'git' ? `${resolution.repo}#${resolution.commit}` : resolution?.sha1 === undefined ? resolution?.tarball : `${resolution.tarball}#${resolution.sha1}`
+    if (!patterns.every((pattern) => Object.hasOwn(installed, pattern) && installed[pattern] === resolved)) commit = undefined
+    // Of two entries of one name and version, either may be the one installed.
+    const id = `${name}@${version}`
+    byVersion.set(id, byVersion.has(id) ? undefined : commit)
+  }
+  return (location, version) => byVersion.get(`${location.slice(location.lastIndexOf('node_modules/') + 'node_modules/'.length)}@${version}`)
+}
+
+// What npm and yarn leave in a node_modules they lay out, and the reader of each one's record.
+const LAYOUTS = [['.package-lock.json', npmRecord], ['.yarn-integrity', yarnRecord]]
+
+// The names pnpm 9 to 12 may give snapshot `key`'s directory in node_modules/.pnpm, as its
+// depPathToFilename (@pnpm/dependency-path) spells them: each character a path can't hold made `+`,
+// `#` too from pnpm 10, and a peer's parentheses `_`; where that is too long or has a capital, cut
+// short before `_` and a hash of it, 26 base32 of an MD5 for pnpm 9, 32 hex of a SHA-256 from pnpm 10,
+// of which the hash alone is kept, as where it is cut depends on the install's
+// virtualStoreDirMaxLength.
+const STORE_NAMES = [
+  [/[\\/:*?"<>|]/gu, (name) => toBase32(hash('md5', name, 'buffer'), { padding: false }).toLowerCase()],
+  [/[\\/:*?"<>|#]/gu, (name) => hash('sha256', name).slice(0, 32)],
+]
+const storeNames = (key) => STORE_NAMES.flatMap(([unsafe, digest]) => {
+  let name = key.replace(unsafe, '+')
+  if (name.includes('(')) name = name.replace(/\)$/u, '').replace(/\)\(|\(|\)/gu, '_')
+  return [name, `_${digest(name)}`]
+})
+const STORE_HASH = /_(?:[\da-f]{32}|[a-z2-7]{26})$/u
+
+// pnpm's: lock.yaml in `store`, a node_modules/.pnpm, the lockfile of what pnpm 9 to 12 installed
+// there, by the directory there each snapshot is in. A git dependency's resolution is the repository
+// and commit, or GitHub's tarball of the commit, and the package's `path` in it (`#path:`) where it is
+// not at the root.
+function pnpmRecord(store, host) {
+  const text = readText(host, join(store, 'lock.yaml'))
+  let packages
+  try {
+    packages = text === null ? undefined : parsePnpmLockfile(text).lockfile?.packages
+  } catch {
+    return NONE // whatever the reader refuses
+  }
+  const byName = new Map()
+  for (const [key, { resolution }] of Object.entries(packages ?? {})) {
+    const commit = resolutionCommit(resolution)
+    if (commit === undefined) continue
+    const directory = (resolution.path ?? '').replace(/^\/+|\/+$/gu, '')
+    const repo = { github: commit.github, ...(isValidRepoField('directory', directory) && { directory }), commit: commit.commit }
+    for (const name of storeNames(key)) byName.set(name, repo)
+  }
+  return (name) => byName.get(name) ?? byName.get(STORE_HASH.exec(name)?.[0])
+}
+
+// A pnpm package's real path, <store>/<dir>/node_modules/<name>, its store a node_modules/.pnpm.
+const PNPM_PACKAGE = /^(.*\/node_modules\/\.pnpm)\/([^/]+)\/node_modules\/(?:@[^/]+\/)?[^/]+$/u
+
+// Each npm dependency of `bundle`, its buckets' paths from `root`, that is a git dependency of a GitHub
+// repository, recorded as its package manager's record has it installed: that repository, over the
+// one its package.json names (a fork's, where that names the one forked), at its root (`''`) or the
+// subdirectory pnpm records, at that commit. A dependency is found by its real path, through the link
+// pnpm installs it by: in a node_modules/.pnpm, by its directory there; else by its location from the
+// nearest directory whose node_modules npm or yarn laid out, from the one its outermost node_modules
+// below the bundle root is in up to that root, whatever a directory above the root is named: a
+// record outside the root is another project's. Metadata, as `repo` is: never checked against the
+// files installed.
+export function pinInstalledCommits(bundle, root, host = diskHost) {
+  const stores = new Map()
+  const layouts = new Map()
+  let top // the bundle root's real path, as each package's is compared with it
+  // The record of `dir`'s node_modules, or null where neither npm nor yarn laid it out; where both
+  // left theirs, neither's, as which was last is not known.
+  const layoutAt = (dir) => {
+    if (!layouts.has(dir)) {
+      const found = LAYOUTS.filter(([file]) => host.stat(join(dir, 'node_modules', file)) !== null)
+      layouts.set(dir, found.length === 0 ? null : found.length === 1 ? found[0][1](dir, host) : NONE)
+    }
+    return layouts.get(dir)
+  }
+  for (const [dir, info] of bundle.modules) {
+    if (info.ecosystem !== 'npm') continue
+    let real
+    try {
+      real = toPosix(host.realpath(resolve(root, dir)))
+    } catch {
+      continue
+    }
+    let repo
+    const pnpm = PNPM_PACKAGE.exec(real)
+    if (pnpm !== null) {
+      const [, store, name] = pnpm
+      if (!stores.has(store)) stores.set(store, pnpmRecord(store, host))
+      repo = stores.get(store)(name)
+    } else {
+      try {
+        top ??= resolve(host.realpath(resolve(root)))
+      } catch {
+        return
+      }
+      const rel = relative(top, real)
+      const parts = toPosix(rel).split('/')
+      const at = parts.indexOf('node_modules')
+      if (relativeEscapes(rel) || at === -1) continue
+      let from = resolve(top, ...parts.slice(0, at))
+      while (layoutAt(from) === null && from !== top) from = dirname(from)
+      const commit = (layoutAt(from) ?? NONE)(toPosix(relative(from, real)), info.version)
+      if (commit !== undefined) repo = { github: commit.github, directory: '', commit: commit.commit }
+    }
+    if (repo !== undefined) bundle.modules.set(dir, { ...info, repo })
+  }
+}

package/src/json-stream.js

@@ -0,0 +1,283 @@
+// Incremental JSON parser over UTF-8 bytes, holding only the value being built and one token in flight.
+// Exactly JSON.parse(Buffer.concat(chunks).toString('utf8')) for any chunking (json-stream.test.js checks it),
+// so a bundle read in a stream can't parse differently from one read whole. Pure: no Node builtins.
+// Not mirrored: Node 24+'s JSON.parse can return a stale escaped key cached by an earlier call (a V8 bug).
+
+const QUOTE = 0x22
+const BACKSLASH = 0x5c
+
+// What the next significant byte may be.
+const VALUE = 0 // any value: the top level, after ':' or after an array's ','
+const ARRAY_FIRST = 1 // after '[': a value or ']'
+const OBJECT_FIRST = 2 // after '{': a key or '}'
+const KEY = 3 // after an object's ',': a key
+const COLON = 4
+const AFTER = 5 // after a member or element: ',' or the container's closer
+const DONE = 6 // the top-level value is complete: whitespace only
+// Inside a token that can straddle chunks.
+const STRING = 7
+const NUMBER = 8
+const LITERAL = 9
+
+const NUMBER_RE = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u
+const LITERALS = new Map([['true', true], ['false', false], ['null', null]])
+
+const isWhitespace = (b) => b === 0x20 || b === 0x0a || b === 0x0d || b === 0x09
+// The bytes a number can span; NUMBER_RE checks its grammar once it ends.
+const isNumberByte = (b) => (b >= 0x30 && b <= 0x39) || b === 0x2d || b === 0x2b || b === 0x2e || b === 0x65 || b === 0x45
+const isLetter = (b) => b >= 0x61 && b <= 0x7a
+
+const hasControlByte = (bytes) => {
+  for (let i = 0; i < bytes.length; i++) if (bytes[i] < 0x20) return true
+  return false
+}
+
+const indexOrEnd = (bytes, byte, from) => {
+  const at = bytes.indexOf(byte, from)
+  return at === -1 ? bytes.length : at
+}
+
+const concat = (parts) => {
+  let length = 0
+  for (const part of parts) length += part.length
+  const out = new Uint8Array(length)
+  let offset = 0
+  for (const part of parts) {
+    out.set(part, offset)
+    offset += part.length
+  }
+  return out
+}
+
+export class JsonStreamParser {
+  // ignoreBOM keeps a leading U+FEFF, as Buffer#toString does; no UTF-8 sequence spans a quote, so per-string decoding is exact.
+  #decoder = new TextDecoder('utf-8', { ignoreBOM: true })
+  #onString
+  #state = VALUE
+  #stack = [] // open containers, innermost last
+  #path = [] // #path[d]: the key or index #stack[d]'s in-flight member lands at
+  #result
+  #offset = 0 // bytes consumed by earlier writes, for error positions
+  #closed = false
+  // Cached indexOf results in the current chunk (-1: not searched yet; its length: none left).
+  #nextQuote = -1
+  #nextBackslash = -1
+  #tokenStart = 0
+  #isKey = false
+  #parts = [] // copied bytes of a string straddling chunks
+  #escaped = false
+  #pendingEscape = false // a chunk ended on a string's backslash
+  #word = '' // a number or literal straddling chunks
+
+  // onString(value, path) sees each string value (never a key) and its return is stored instead.
+  // `path` is the live key/index path: read it, never keep or mutate it.
+  constructor({ onString } = {}) {
+    this.#onString = onString
+  }
+
+  // A chunk may be reused once write() returns: the bytes of a token left open are copied.
+  write(bytes) {
+    if (this.#closed) throw new Error('JsonStreamParser: write after end or failure')
+    if (!ArrayBuffer.isView(bytes)) throw new TypeError('JsonStreamParser: write() takes a Uint8Array')
+    // A plain Uint8Array view: a Buffer's slice() doesn't copy, and its indexOf/subarray are slower.
+    const view = bytes.constructor === Uint8Array ? bytes : new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    try {
+      this.#consume(view)
+    } catch (error) {
+      this.#closed = true
+      throw error
+    }
+    this.#offset += view.length
+  }
+
+  end() {
+    if (this.#closed) throw new Error('JsonStreamParser: end after end or failure')
+    this.#closed = true
+    if (this.#state === NUMBER || this.#state === LITERAL) this.#finishWord()
+    if (this.#state !== DONE) throw new SyntaxError(`Unexpected end of JSON input at byte ${this.#offset}`)
+    const result = this.#result
+    this.#result = undefined
+    return result
+  }
+
+  #fail(message, i) {
+    throw new SyntaxError(`${message} at byte ${this.#offset + i}`)
+  }
+
+  #consume(bytes) {
+    const n = bytes.length
+    this.#nextQuote = -1
+    this.#nextBackslash = -1
+    let i = 0
+    while (i < n) {
+      const state = this.#state
+      if (state === STRING) {
+        i = this.#string(bytes, i)
+      } else if (state === NUMBER || state === LITERAL) {
+        i = this.#scanWord(bytes, i)
+      } else if (isWhitespace(bytes[i])) {
+        i += 1
+      } else {
+        i = this.#structural(bytes[i], i)
+      }
+    }
+  }
+
+  #structural(b, i) {
+    const state = this.#state
+    const isArray = Array.isArray(this.#stack.at(-1))
+    if ((state === AFTER || state === ARRAY_FIRST || state === OBJECT_FIRST) && b === (isArray ? 0x5d : 0x7d)) {
+      this.#close()
+      return i + 1
+    }
+    if (state === AFTER) {
+      if (b !== 0x2c) this.#fail(`Unexpected byte 0x${b.toString(16)} after a value`, i)
+      this.#state = isArray ? VALUE : KEY
+      return i + 1
+    }
+    if (state === COLON) {
+      if (b !== 0x3a) this.#fail(`Expected ':' after a key, got byte 0x${b.toString(16)}`, i)
+      this.#state = VALUE
+      return i + 1
+    }
+    if (state === OBJECT_FIRST || state === KEY) {
+      if (b !== QUOTE) this.#fail(`Expected a string key, got byte 0x${b.toString(16)}`, i)
+      this.#startToken(STRING, i)
+      this.#isKey = true
+      return i + 1
+    }
+    if (state === DONE) this.#fail(`Unexpected byte 0x${b.toString(16)} after the JSON value`, i)
+    // VALUE or ARRAY_FIRST
+    if (isArray) this.#path[this.#stack.length - 1] = this.#stack.at(-1).length
+    if (b === QUOTE) {
+      this.#startToken(STRING, i)
+      this.#isKey = false
+      return i + 1
+    }
+    if (b === 0x7b || b === 0x5b) {
+      this.#stack.push(b === 0x7b ? {} : [])
+      this.#path.push(undefined)
+      this.#state = b === 0x7b ? OBJECT_FIRST : ARRAY_FIRST
+      return i + 1
+    }
+    if (b === 0x2d || (b >= 0x30 && b <= 0x39)) {
+      this.#startToken(NUMBER, i)
+      return i
+    }
+    if (b === 0x74 || b === 0x66 || b === 0x6e) {
+      this.#startToken(LITERAL, i)
+      return i
+    }
+    return this.#fail(`Unexpected byte 0x${b.toString(16)} where a value was expected`, i)
+  }
+
+  #startToken(state, i) {
+    this.#state = state
+    this.#tokenStart = this.#offset + i
+  }
+
+  #string(bytes, start) {
+    const n = bytes.length
+    let i = start
+    if (this.#pendingEscape) {
+      this.#pendingEscape = false
+      i += 1
+    }
+    for (;;) {
+      if (this.#nextQuote < i) this.#nextQuote = indexOrEnd(bytes, QUOTE, i)
+      if (this.#nextBackslash < i) this.#nextBackslash = indexOrEnd(bytes, BACKSLASH, i)
+      const quote = this.#nextQuote
+      const backslash = this.#nextBackslash
+      if (backslash < quote) {
+        this.#escaped = true
+        if (backslash + 1 === n) {
+          this.#pendingEscape = true
+          break
+        }
+        i = backslash + 2
+      } else if (quote === n) {
+        break
+      } else {
+        this.#finishString(bytes.subarray(start, quote))
+        return quote + 1
+      }
+    }
+    this.#parts.push(bytes.slice(start))
+    return n
+  }
+
+  #finishString(tail) {
+    let bytes = tail
+    if (this.#parts.length > 0) {
+      this.#parts.push(tail)
+      bytes = concat(this.#parts)
+      this.#parts = []
+    }
+    let value = this.#decoder.decode(bytes)
+    if (this.#escaped) {
+      // JSON.parse handles the escapes, and rejects raw control bytes.
+      this.#escaped = false
+      try {
+        value = JSON.parse(`"${value}"`)
+      } catch (cause) {
+        throw new SyntaxError(`Bad string at byte ${this.#tokenStart}`, { cause })
+      }
+    } else if (hasControlByte(bytes)) {
+      throw new SyntaxError(`Bad control character in string at byte ${this.#tokenStart}`)
+    }
+    if (this.#isKey) {
+      this.#path[this.#path.length - 1] = value
+      this.#state = COLON
+    } else {
+      this.#value(this.#onString === undefined ? value : this.#onString(value, this.#path))
+    }
+  }
+
+  #scanWord(bytes, i) {
+    const n = bytes.length
+    const isNumber = this.#state === NUMBER
+    let j = i
+    while (j < n && (isNumber ? isNumberByte(bytes[j]) : isLetter(bytes[j]))) j += 1
+    this.#word += this.#decoder.decode(bytes.subarray(i, j))
+    if (j === n) return n
+    this.#finishWord()
+    return j
+  }
+
+  #finishWord() {
+    const word = this.#word
+    this.#word = ''
+    if (this.#state === NUMBER) {
+      if (!NUMBER_RE.test(word)) throw new SyntaxError(`Bad number at byte ${this.#tokenStart}`)
+      this.#value(Number(word))
+    } else {
+      if (!LITERALS.has(word)) throw new SyntaxError(`Bad literal at byte ${this.#tokenStart}`)
+      this.#value(LITERALS.get(word))
+    }
+  }
+
+  #close() {
+    this.#path.pop()
+    this.#value(this.#stack.pop())
+  }
+
+  #value(value) {
+    const depth = this.#stack.length
+    if (depth === 0) {
+      this.#result = value
+      this.#state = DONE
+      return
+    }
+    const container = this.#stack[depth - 1]
+    const key = this.#path[depth - 1]
+    if (Array.isArray(container)) {
+      container.push(value)
+    } else if (key === '__proto__') {
+      // JSON.parse defines an own data property; assignment would hit Object.prototype's setter.
+      Object.defineProperty(container, key, { value, writable: true, enumerable: true, configurable: true })
+    } else {
+      container[key] = value
+    }
+    this.#state = AFTER
+  }
+}

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()