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

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.3",
+  "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
     "./esbuild": "./src/esbuild.js",
@@ -9,16 +9,21 @@
     "./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/audit.js",
     "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 +44,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/audit.js

@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs'
+import { brotliDecompressSync } from 'node:zlib'
+
+import { advisories } from './apis/npm/index.js'
+import semver from './apis/npm/semver.cjs'
+import { Bundle } from './bundle.js'
+import { Lockfile } from './lockfile.js'
+
+function parseFile(file) {
+  let buf
+  try {
+    buf = readFileSync(file)
+  } catch (cause) {
+    if (cause.code === 'ENOENT') throw new Error(`File not found: ${file}`, { cause })
+    throw new Error(`Failed to read ${file}: ${cause.message}`, { cause })
+  }
+  // Lockfiles are JSON text starting with `{`; code/resource bundles are
+  // brotli-compressed JSON. Sniff to route to the right parser so its
+  // diagnostic surfaces on failure.
+  if (buf[0] === 0x7b /* '{' */) {
+    try {
+      return Lockfile.parse(buf.toString('utf8'))
+    } catch (cause) {
+      throw new Error(`Failed to parse stasis lockfile: ${file}`, { cause })
+    }
+  }
+  let text
+  try {
+    text = brotliDecompressSync(buf).toString('utf8')
+  } catch (cause) {
+    throw new Error(`Failed to read ${file} as a stasis bundle (not brotli)`, { cause })
+  }
+  // Code bundles carry `formats`/`imports`; resource bundles don't. Route on shape.
+  try {
+    const isCode = JSON.parse(text).formats !== undefined
+    return isCode ? Bundle.parseCode(text) : Bundle.parseResources(text)
+  } catch (cause) {
+    throw new Error(`Failed to parse stasis bundle: ${file}`, { cause })
+  }
+}
+
+// Only audit installed dependencies; workspace/first-party packages live under
+// non-`node_modules` keys in .modules (Lockfile/Bundle merge sources in) and
+// shouldn't be sent to the public registry — they leak names and produce noise.
+export function collectPackagesFromFile(file) {
+  const out = []
+  for (const [dir, { name, version }] of parseFile(file).modules) {
+    if (!dir.includes('node_modules')) continue
+    if (name && version) out.push({ name, version })
+  }
+  return out
+}
+
+export function collectPackages(files) {
+  const seen = new Set()
+  const out = []
+  for (const file of files) {
+    for (const { name, version } of collectPackagesFromFile(file)) {
+      const key = `${name}@${version}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      out.push({ name, version })
+    }
+  }
+  return out.toSorted((a, b) => a.name.localeCompare(b.name) || semver.compare(a.version, b.version))
+}
+
+const SEVERITY_ORDER = { critical: 0, high: 1, moderate: 2, low: 3, info: 4, none: 5 }
+
+export function flattenAdvisories(result, packages = []) {
+  const installed = new Map()
+  for (const { name, version } of packages) {
+    if (!installed.has(name)) installed.set(name, [])
+    installed.get(name).push(version)
+  }
+  const rows = []
+  for (const [pkg, list] of Object.entries(result)) {
+    if (!Array.isArray(list)) continue
+    const installedVersions = installed.get(pkg) ?? []
+    for (const adv of list) {
+      const range = adv.vulnerable_versions ?? ''
+      const affected = range
+        ? installedVersions.filter((v) => semver.satisfies(v, range))
+        : installedVersions
+      // npm occasionally returns advisories whose vulnerable range matches none
+      // of the versions we submitted; drop them so the table (and the CLI exit
+      // code) reflect only real hits.
+      if (installedVersions.length > 0 && affected.length === 0) continue
+      rows.push({
+        package: pkg,
+        installed: affected.join(', '),
+        vulnerable: range,
+        severity: adv.severity ?? '',
+        title: adv.title ?? '',
+        url: adv.url ?? '',
+      })
+    }
+  }
+  rows.sort((a, b) => {
+    const sa = SEVERITY_ORDER[a.severity] ?? 99
+    const sb = SEVERITY_ORDER[b.severity] ?? 99
+    if (sa !== sb) return sa - sb
+    if (a.package !== b.package) return a.package < b.package ? -1 : 1
+    return a.title < b.title ? -1 : 1
+  })
+  return rows
+}
+
+// Line breaks in npm advisory titles would otherwise break the box layout.
+// Covers LF, bare CR (and CRLF), and U+2028 / U+2029 line/paragraph separators.
+const cell = (v) => String(v ?? '').replace(/[\r\n\u2028\u2029]+/gu, ' ')
+
+export function formatTable(rows, columns) {
+  if (rows.length === 0) return ''
+  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length)))
+  const pad = (s, w) => s.padEnd(w)
+  const line = (l, m, r, fill) => l + widths.map((w) => fill.repeat(w + 2)).join(m) + r
+  const row = (vals) => '│ ' + vals.map((v, i) => pad(cell(v), widths[i])).join(' │ ') + ' │'
+  return [
+    line('┌', '┬', '┐', '─'),
+    row(columns),
+    line('├', '┼', '┤', '─'),
+    ...rows.map((r) => row(columns.map((c) => r[c]))),
+    line('└', '┴', '┘', '─'),
+  ].join('\n')
+}
+
+export async function audit(files) {
+  const packages = collectPackages(files)
+  if (packages.length === 0) {
+    return { packages, advisories: {}, rows: [] }
+  }
+  const result = await advisories(packages)
+  const rows = flattenAdvisories(result, packages)
+  return { packages, advisories: result, rows }
+}
+
+export function printAuditReport({ packages, rows }, { out = process.stdout, err = process.stderr } = {}) {
+  err.write(`Scanned ${packages.length} package${packages.length === 1 ? '' : 's'}\n`)
+  if (packages.length === 0) {
+    err.write('No node_modules entries found in the input files\n')
+    return
+  }
+  if (rows.length === 0) {
+    err.write('No advisories found\n')
+    return
+  }
+  out.write(formatTable(rows, ['severity', 'package', 'installed', 'vulnerable', 'title', 'url']) + '\n')
+}

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, baseDir })
+
+  // 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,210 @@
+// 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 { createRequire } from 'node:module'
+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)
+}
+
+// Resolve a Solidity import specifier to a baseDir-relative POSIX path,
+// trying three strategies in order:
+//   1. user remappings (longest prefix wins)
+//   2. relative path (`./...` or `../...`); traversal above the project
+//      root returns null instead of clamping
+//   3. Node's CJS resolver via createRequire, anchored at the importing
+//      source — only when `baseDir` is provided and the specifier looks
+//      like a scoped npm package (`@scope/pkg/sub/path`)
+// Returns null when no strategy resolves the import.
+export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir } = {}) {
+  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, '')
+    return (remaining ? `${target}/${remaining}` : target).replace(/^\.\//u, '')
+  }
+
+  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('/')
+  }
+
+  // Node-style `@scope/pkg/sub/path`. createRequire is anchored at the
+  // importing source so nested node_modules resolve like Node would
+  // (a file under `node_modules/foo/` finds its deps in
+  // `foo/node_modules/` before walking up). `..` segments in the
+  // subpath are rejected so a crafted specifier can't escape the
+  // resolved package via require.resolve's own path normalization.
+  if (baseDir && specifier.startsWith('@')) {
+    const parts = specifier.split('/')
+    if (parts.length < 3) return null
+    if (parts.slice(2).includes('..')) return null
+    try {
+      const abs = createRequire(resolve(baseDir, fromFile)).resolve(specifier)
+      const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
+      if (!rel.startsWith('..') && !isAbsolute(rel)) return rel
+    } catch { /* package missing, exports map blocks the subpath, … */ }
+  }
+
+  return null
+}
+
+// Build the { sources, resolutions, missing } triple from a Map of
+// already-loaded Solidity sources plus optional remappings. Imports that
+// resolve via remappings/relative/Node win; as a final fallback an
+// import specifier that matches a stored key verbatim (etherscan
+// bundles, hardhat flat layouts) is accepted. `missing` lists every
+// (spec, from) pair that could not be resolved or that resolved to a
+// file not loaded into `sources`.
+export function buildSolidityTree(sources, { remappings = [], baseDir } = {}) {
+  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, baseDir })
+      if (resolved && !sources.has(resolved)) resolved = null
+      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 resolved
+// imports and reading each file exactly once. Files in the same wave
+// are read in parallel; the next wave depends on the imports
+// discovered in the previous one. Caller-listed entries are also
+// accepted as verbatim non-relative import targets (Foundry-style
+// `import "src/A.sol"`).
+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
+    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, baseDir })
+        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, baseDir })
+}