@exodus/stasis 1.0.0-alpha.1 → 1.0.0-alpha.2

package/README.md

@@ -1,4 +1,4 @@
-# `@exodus/stasis`
+# <img src="./logo.svg" alt="" width="39" height="39" valign="bottom" /> `@exodus/stasis`
 
 Analyzeable source code bundles with resolutions + per-file lockfiles
 

package/bin/stasis.js

@@ -20,8 +20,7 @@ assert(basename(jsname) === 'stasis' || pathsEqual(jsname, fileURLToPath(import.
 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 bundle [--mapping=path/to/remappings(.txt|.toml)] [--output=path/to/out.stasis.code.br] path/to/file.sol ...
  stasis prune [path/to/project]
  stasis audit path/to/file ...
 `.trim())
@@ -77,7 +76,30 @@ if (command === '-v' || command === '--version') {
   const [code] = await once(child, 'close')
   process.exitCode = code
 } else if (command === 'bundle') {
-  usage('bundle command is not implemented yet')
+  const flags = []
+  const valueFlags = new Set(['--mapping', '--output', '-o'])
+  while (argv.length > 0 && (argv[0].startsWith('-') || valueFlags.has(flags.at(-1)))) {
+    flags.push(argv.shift())
+  }
+  const options = {
+    mapping: { type: 'string' },
+    output: { type: 'string', short: 'o' },
+  }
+  let values
+  try {
+    ({ values } = parseArgs({ args: flags, options }))
+  } catch (cause) {
+    usage(`Error: ${cause.message}`)
+  }
+  if (argv.length === 0) usage('Nothing to bundle: no .sol file given')
+  if (!argv.every((f) => f.endsWith('.sol'))) usage('Error: bundle only accepts .sol files')
+  const { bundleCommand } = await import('../src/cmd/bundle.js')
+  await bundleCommand({
+    cwd: process.cwd(),
+    entries: argv,
+    mappingFile: values.mapping,
+    output: values.output,
+  })
 } 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()

package/logo.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" aria-label="Stasis" viewBox="0 0 128 128">
+  <defs>
+    <linearGradient id="a" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0%" stop-color="#1f9cff"/>
+      <stop offset="60%" stop-color="#8c5bfe"/>
+      <stop offset="100%" stop-color="#b85bfe"/>
+    </linearGradient>
+  </defs>
+  <rect width="128" height="128" fill="rgba(150,150,150,0.09)" rx="28" ry="28"/>
+  <circle cx="64" cy="64" r="28.16" fill="url(#a)"/>
+</svg>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-alpha.1",
-  "description": "A research project",
+  "version": "1.0.0-alpha.2",
+  "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
     "./esbuild": "./src/esbuild.js",
@@ -9,16 +9,20 @@
     "./loader": "./src/loader.js",
     "./bundle": "./src/bundle.js",
     "./lockfile": "./src/lockfile.js",
-    "./prune": "./src/prune.js"
+    "./prune": "./src/prune.js",
+    "./logo.svg": "./logo.svg"
   },
   "files": [
     "bin/stasis.js",
+    "logo.svg",
     "src/apis/npm/index.js",
     "src/apis/npm/semver.cjs",
     "src/bundle.js",
+    "src/cmd/bundle.js",
     "src/config.js",
     "src/esbuild.js",
     "src/loader.js",
+    "src/loaders/solidity.js",
     "src/lockfile.js",
     "src/prune.js",
     "src/state.js",
@@ -39,14 +43,14 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ExodusMovement/stasis.git"
+    "url": "git+https://github.com/ExodusOSS/stasis.git"
   },
   "author": "Exodus Movement, Inc.",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/ExodusMovement/stasis/issues"
+    "url": "https://github.com/ExodusOSS/stasis/issues"
   },
-  "homepage": "https://github.com/ExodusMovement/stasis#readme",
+  "homepage": "https://github.com/ExodusOSS/stasis#readme",
   "devDependencies": {
     "@exodus/bytes": "^1.15.0",
     "esbuild": "^0.27.3",

package/src/cmd/bundle.js

@@ -0,0 +1,188 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, posix, relative, resolve } from 'node:path'
+import { brotliCompressSync } from 'node:zlib'
+
+import { Bundle } from '../bundle.js'
+import { splitNodeModulesPath } from '../util.js'
+import {
+  buildSolidityTree,
+  collectSolidityFilesFromDisk,
+  readRemappingsFile,
+} from '../loaders/solidity.js'
+
+// Fallback package identity for the workspace bucket when no package.json
+// with a name+version can be found by walking up from any of the bundled
+// files. Bundle.parseCode requires every workspace/module bucket to have
+// both fields, so we have to attest something.
+const SOLIDITY_WORKSPACE_NAME = 'solidity-bundle'
+const SOLIDITY_WORKSPACE_VERSION = '0.0.0'
+const SOLIDITY_FORMAT = 'solidity'
+
+// Walk up from the file's directory looking for the nearest package.json
+// with both `name` and `version`. Returns { pkgDir, name, version }
+// (pkgDir relative to `baseDir`, "." for the project root) or null when no
+// such package.json exists at or above the file.
+function findPackageMetadata(baseDir, fileRelPath) {
+  let dir = dirname(fileRelPath)
+  while (true) {
+    const pkgPath = join(baseDir, dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        if (pkg.name && pkg.version) {
+          return { pkgDir: dir, name: pkg.name, version: pkg.version }
+        }
+      } catch { /* malformed — keep walking */ }
+    }
+    if (dir === '.' || dir === '/' || dir === '') return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function normalizeEntries(entries, cwd) {
+  const baseDir = resolve(cwd)
+  return entries.map((e) => {
+    const abs = resolve(cwd, e)
+    const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
+    // On Windows, `path.relative()` returns an absolute path when `abs` is on
+    // a different drive than `baseDir` — that wouldn't start with `..` but
+    // still escapes, so reject both forms.
+    if (rel.startsWith('..') || isAbsolute(rel)) throw new Error(`Entry escapes baseDir: ${e}`)
+    return rel.replace(/^\.\//u, '')
+  })
+}
+
+// Deepest directory that is a parent of every file in `paths`, expressed
+// relative to `cwd`. `paths` may be POSIX-relative-to-cwd; entries that
+// escape cwd (e.g. `../deps/X.sol` via remapping) push the result above
+// cwd, in which case the returned path starts with `..`. Returns "." when
+// the outermost directory IS cwd itself.
+export function outermostDir(paths, cwd) {
+  if (paths.length === 0) return '.'
+  const cwdAbs = posix.resolve(cwd.replaceAll(/\\/gu, '/'))
+  const absDirs = paths.map((p) => posix.dirname(posix.resolve(cwdAbs, p)))
+  const partsList = absDirs.map((d) => d.split('/'))
+  const common = []
+  for (let i = 0; i < partsList[0].length; i++) {
+    const c = partsList[0][i]
+    if (!partsList.every((parts) => parts[i] === c)) break
+    common.push(c)
+  }
+  const absCommon = common.join('/') || '/'
+  const rel = posix.relative(cwdAbs, absCommon)
+  return rel === '' ? '.' : rel
+}
+
+// Build a stasis Bundle (in-memory) from a list of entry .sol files and
+// an optional mapping file. The mapping file (foundry.toml or
+// remappings.txt) is parsed for remappings but NOT included in the
+// bundle's sources. Returns the constructed `Bundle`.
+export async function buildSolidityBundle({ cwd = process.cwd(), entries, mappingFile } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    throw new Error('buildSolidityBundle: at least one entry .sol file is required')
+  }
+  for (const e of entries) {
+    if (!e.endsWith('.sol')) throw new Error(`buildSolidityBundle: not a .sol file: ${e}`)
+  }
+
+  const baseDir = resolve(cwd)
+  const remappings = mappingFile ? await readRemappingsFile(resolve(cwd, mappingFile)) : []
+  const normalized = normalizeEntries(entries, cwd)
+
+  const sources = await collectSolidityFilesFromDisk(baseDir, normalized, remappings)
+  const { resolutions, missing } = buildSolidityTree(sources, { remappings })
+
+  // Bundles must be self-contained. Refuse to write one when an entry
+  // can't be loaded from disk, or when any in-bundle file has an import
+  // we couldn't resolve — otherwise downstream consumers would silently
+  // operate on a partial set of sources.
+  const issues = []
+  for (const entry of normalized) {
+    if (!sources.has(entry)) issues.push(`Missing entry: ${entry}`)
+  }
+  for (const { spec, from } of missing) {
+    issues.push(`Unresolved import: ${spec} from ${from}`)
+  }
+  if (issues.length > 0) {
+    throw new Error(`Solidity bundle has unresolved imports:\n${issues.map((s) => `  ${s}`).join('\n')}`)
+  }
+
+  // Partition every loaded .sol file into a per-package bucket. The
+  // bucket is the directory holding the nearest package.json with a
+  // name+version. node_modules files land in `node_modules/<pkg>` buckets
+  // (or deeper, when a nested package.json claims the file); workspace
+  // files land in their nearest workspace package.json's dir, or in the
+  // fallback "." bucket with placeholder metadata when no package.json
+  // could be found.
+  const modules = new Map()
+  const ensureBucket = (dir, name, version) => {
+    if (!modules.has(dir)) modules.set(dir, { name, version, files: Object.create(null) })
+    return modules.get(dir)
+  }
+
+  for (const [path, content] of sources) {
+    const meta = findPackageMetadata(baseDir, path)
+    const inNodeModules = splitNodeModulesPath(path) !== null
+    if (meta) {
+      // A file inside node_modules whose nearest package.json is the
+      // workspace root would silently land in the workspace bucket and
+      // hide the misconfigured dependency — refuse instead.
+      if (inNodeModules && !meta.pkgDir.includes('node_modules')) {
+        throw new Error(`No package.json with name+version found for ${path}`)
+      }
+      const rel = meta.pkgDir === '.' ? path : path.slice(meta.pkgDir.length + 1)
+      ensureBucket(meta.pkgDir, meta.name, meta.version).files[rel] = content
+    } else {
+      // Files under node_modules without any discoverable package.json
+      // would otherwise leak into the workspace bucket; that's a project
+      // misconfiguration, surface it loudly.
+      if (inNodeModules) throw new Error(`No package.json with name+version found for ${path}`)
+      ensureBucket('.', SOLIDITY_WORKSPACE_NAME, SOLIDITY_WORKSPACE_VERSION).files[path] = content
+    }
+  }
+
+  const formats = new Map()
+  for (const path of sources.keys()) formats.set(path, SOLIDITY_FORMAT)
+
+  // Solidity imports don't depend on Node conditions; key them under a
+  // dedicated "solidity" bucket rather than the wildcard "*" used for
+  // JS code bundles.
+  const importsForKey = new Map()
+  for (const [parent, specMap] of resolutions) importsForKey.set(parent, specMap)
+  const imports = new Map([['solidity', importsForKey]])
+
+  return new Bundle({
+    config: { scope: 'full' },
+    entries: new Set(normalized),
+    modules,
+    formats,
+    imports,
+  })
+}
+
+// Run the bundle CLI command end-to-end. Always produces a brotli-compressed
+// stasis bundle (matching the on-disk format of `stasis.code.br`). When
+// `output` is provided, writes to that path; otherwise writes to stdout.
+// Prints a one-line `[stasis] Bundled <n> files from <dir> to <dest>` summary
+// to stderr so it doesn't interleave with the binary output on stdout.
+export async function bundleCommand({ cwd = process.cwd(), entries, mappingFile, output } = {}) {
+  const bundle = await buildSolidityBundle({ cwd, entries, mappingFile })
+  const data = brotliCompressSync(bundle.serializeCode())
+  if (output) {
+    const outAbs = resolve(cwd, output)
+    mkdirSync(dirname(outAbs), { recursive: true })
+    writeFileSync(outAbs, data)
+  } else {
+    process.stdout.write(data)
+  }
+  // Bundle.sources flattens every per-package bucket into project-relative
+  // paths, so the summary reflects every file we wrote — workspace and
+  // node_modules alike — not just the workspace bucket.
+  const files = [...bundle.sources.keys()]
+  const fromDir = outermostDir(files, resolve(cwd))
+  const dest = output ?? '<stdout>'
+  console.warn(`[stasis] Bundled ${files.length} files from ${fromDir} to ${dest}`)
+  return bundle
+}

package/src/loaders/solidity.js

@@ -0,0 +1,214 @@
+// Based on DeepView's Solidity loader.
+// https://github.com/PreventiveMeasures/deepview/blob/main/src/loaders/solidity.js
+//
+// Adapted to produce a `{ sources, resolutions }` pair only. The mapping
+// file (foundry.toml or remappings.txt) is read to extract `remappings`,
+// but is itself not included in `sources`.
+
+import { readFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+
+const SOL_IMPORT_RE = /import\s[^"']*["']([^"']+)["']/gu
+
+export function extractSolImports(content) {
+  return [...content.matchAll(SOL_IMPORT_RE)].map((m) => m[1])
+}
+
+export function parseRemappingsFromToml(tomlContent) {
+  const match = tomlContent.match(/remappings\s*=\s*\[([\s\S]*?)\]/u)
+  if (!match) return []
+  return parseRemappings([...match[1].matchAll(/["']([^"']+)["']/gu)].map((m) => m[1]).join('\n'))
+}
+
+export function parseRemappings(content) {
+  return content.trim().split('\n').map((entry) => {
+    const eqIdx = entry.indexOf('=')
+    if (eqIdx === -1) return null
+    return { prefix: entry.slice(0, eqIdx), target: entry.slice(eqIdx + 1) }
+  }).filter(Boolean)
+}
+
+// Returns a candidate resolved path, or null if the specifier doesn't match
+// any remapping and isn't a relative import. The caller is responsible for
+// checking whether the resolved path actually exists in `sources` (the
+// etherscan bundle's cnames are exact-match keys — `@openzeppelin/…` lives
+// alongside `contracts/Foo.sol` — so a non-relative, non-remapped specifier
+// may still be a hit when matched verbatim against the bundle). Logging
+// "Missing import" also lives at the callsite because only the callsite
+// knows whether that verbatim fallback matched.
+export function resolveSolImport(specifier, fromFile, remappings) {
+  // Try remappings (longest prefix match)
+  let best = null
+  for (const { prefix, target } of remappings) {
+    if (specifier.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) {
+      best = { prefix, target }
+    }
+  }
+  if (best) {
+    const target = best.target.replace(/\/$/u, '')
+    const remaining = specifier.slice(best.prefix.length).replace(/^\//u, '')
+    const result = remaining ? `${target}/${remaining}` : target
+    return result.replace(/^\.\//u, '')
+  }
+
+  // Relative import. `..` segments that would traverse above the project
+  // root return null instead of silently clamping to root — clamping would
+  // change the import target into something the source never asked for.
+  if (specifier.startsWith('.')) {
+    const fromDir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : ''
+    const parts = [...(fromDir ? fromDir.split('/') : []), ...specifier.split('/')]
+    const resolved = []
+    for (const part of parts) {
+      if (part === '.' || part === '') continue
+      if (part === '..') {
+        if (resolved.length === 0) return null
+        resolved.pop()
+      } else {
+        resolved.push(part)
+      }
+    }
+    return resolved.join('/')
+  }
+
+  return null
+}
+
+// Build the { sources, resolutions, missing } triple from a Map of
+// already-loaded Solidity sources (any key format — relative paths for
+// disk-loaded projects, `${address}/${cname}` for etherscan, etc.) plus
+// optional remappings. Imports that resolve via remappings/relative paths
+// win; as a fallback we also accept an import specifier that matches a
+// stored key verbatim (etherscan bundles imports like
+// `@openzeppelin/contracts/.../IERC20.sol` which is itself a stored
+// cname). `missing` lists every (spec, from) pair that could not be
+// resolved or that resolved to a file that wasn't loaded into `sources`.
+export function buildSolidityTree(sources, { remappings = [] } = {}) {
+  const resolutions = new Map()
+  const missing = []
+  for (const [path, content] of sources) {
+    const specMap = new Map()
+    for (const spec of extractSolImports(content)) {
+      let resolved = resolveSolImport(spec, path, remappings)
+      if (resolved && !sources.has(resolved)) resolved = null
+      // Verbatim fallback: many Solidity ecosystems (etherscan bundles,
+      // hardhat flat layouts) ship `@openzeppelin/...` imports as literal
+      // keys in the source map. If the remap/relative resolution didn't
+      // hit but the bundle has the specifier itself as a key, use it.
+      if (!resolved && sources.has(spec)) resolved = spec
+      if (resolved) {
+        specMap.set(spec, resolved)
+      } else {
+        console.warn(`[loader.solidity] Missing import: ${spec} from ${path}`)
+        missing.push({ spec, from: path })
+      }
+    }
+    resolutions.set(path, specMap)
+  }
+  return { sources, resolutions, missing }
+}
+
+// Walk the filesystem starting from `entries`, following relative/remapped
+// imports and reading each file exactly once. Returns a Map<relPath, content>
+// suitable for passing into buildSolidityTree. Files in the same wave are
+// read in parallel; subsequent waves depend on the imports discovered in
+// the previous one.
+//
+// Specifiers that exactly match one of the explicit entries (the file
+// list passed by the caller) are accepted as-is, even when they don't
+// match any remapping. Solidity projects routinely write
+// `import "src/A.sol"` and rely on solc's include-path / Foundry's
+// remap-from-root behavior; here we don't have a true include path,
+// but if the caller listed `src/A.sol` themselves we know the path is
+// intentional and resolves to that file. Mirrors the `sources.has(spec)`
+// fallback in `buildSolidityTree`, but applied during the walk so the
+// file actually gets loaded into `sources`.
+export async function collectSolidityFilesFromDisk(baseDir, entries, remappings) {
+  const sources = new Map()
+  const knownEntries = new Set(entries)
+
+  const processWave = async (wave) => {
+    const toLoad = [...new Set(wave)].filter((p) => !sources.has(p))
+    if (toLoad.length === 0) return
+    // A resolved path that doesn't exist on disk is treated like an
+    // unresolved import: warn and skip rather than aborting the entire
+    // walk. Other read errors (EACCES, EIO, …) still propagate.
+    const reads = await Promise.all(
+      toLoad.map(async (relPath) => {
+        try {
+          return [relPath, await readFile(join(baseDir, relPath), 'utf8')]
+        } catch (err) {
+          if (err.code === 'ENOENT') {
+            console.warn(`[loader.solidity] Missing import: ${relPath}`)
+            return null
+          }
+          throw err
+        }
+      })
+    )
+    const next = []
+    for (const entry of reads) {
+      if (!entry) continue
+      const [relPath, content] = entry
+      sources.set(relPath, content)
+      for (const spec of extractSolImports(content)) {
+        let resolved = resolveSolImport(spec, relPath, remappings)
+        if (!resolved && knownEntries.has(spec)) resolved = spec
+        if (resolved) {
+          if (!sources.has(resolved)) next.push(resolved)
+        } else {
+          console.warn(`[loader.solidity] Missing import: ${spec} from ${relPath}`)
+        }
+      }
+    }
+    await processWave(next)
+  }
+
+  await processWave(entries)
+  return sources
+}
+
+// Read a foundry.toml or remappings.txt mapping file and return its parsed
+// remappings. The mapping file itself is NOT included in the loaded sources.
+export async function readRemappingsFile(mappingFile) {
+  const content = await readFile(mappingFile, 'utf8')
+  if (mappingFile.endsWith('.toml')) return parseRemappingsFromToml(content)
+  return parseRemappings(content)
+}
+
+// Reject absolute paths and `..`-escaping paths in a `.sol.txt` listing so
+// a malicious or sloppy listing can't trick the loader into reading
+// arbitrary 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('/')
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`${label} escapes baseDir: ${candidate}`)
+  }
+}
+
+// High-level: takes an optional .sol.txt listing file. The first line may
+// be a `*.toml` or `remappings.txt` mapping file (resolved relative to the
+// listing); the remaining lines are `*.sol` files. Mirrors the DeepView
+// loader's interface.
+export async function loadSolidity(solTxtFile) {
+  const baseDir = dirname(resolve(solTxtFile))
+  const listing = await readFile(solTxtFile, 'utf8')
+  const lines = listing.split('\n').map((l) => l.trim()).filter(Boolean)
+  if (lines.length === 0) throw new Error(`Empty Solidity listing: ${solTxtFile}`)
+
+  let remappings = []
+  if (lines[0].endsWith('.toml') || lines[0].endsWith('remappings.txt')) {
+    const mapping = lines.shift()
+    assertWithinBase(baseDir, mapping, 'Mapping path')
+    remappings = await readRemappingsFile(join(baseDir, mapping))
+  }
+
+  if (!lines.every((line) => line.endsWith('.sol'))) {
+    throw new Error(`Solidity listing must only contain .sol files: ${solTxtFile}`)
+  }
+
+  const entries = lines.map((l) => l.replace(/^\.\//u, ''))
+  for (const e of entries) assertWithinBase(baseDir, e, 'Entry path')
+  const sources = await collectSolidityFilesFromDisk(baseDir, entries, remappings)
+  return buildSolidityTree(sources, { remappings })
+}