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

package/src/scan.js

@@ -1,60 +1,65 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { extname, resolve as resolvePath, relative } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { createRequire, isBuiltin, findPackageJSON } from 'node:module'
+import { createRequire, isBuiltin } from 'node:module'
 import assert from 'node:assert/strict'
+import { packageType } from '@exodus/stasis-core/bundle-util'
+import { classifyExtension, classifyFormat } from '@exodus/stasis-core/util'
 
-// Static require/import graph walker. Reads source files and parses them; never
-// loads or executes any user code. Resolves specifiers through Node's own
-// resolver (`createRequire(parent).resolve(spec, { conditions: Set })`), which
-// reads package.json manifests and applies `exports` conditions but never runs
-// the target module. Dynamic specifiers (`require(name)`, `import('./'+x)`)
-// are recorded as unresolved -- a fundamental limit of static analysis for
-// CJS, not a tooling shortcoming. Files that fail to parse are recorded in
-// `parseErrors` (and flagged with `parseError` in `files`): for script (CJS)
-// files oxc's recovered AST still yields the edges (Node's module wrapper
-// accepts code oxc rejects, e.g. top-level `return`), while module files keep
-// no edges -- a missed static edge is a hole consumers can't enumerate.
+// Static require/import graph walker: parses source, never loads or executes user code.
+// Dynamic specifiers (`require(name)`, `import('./'+x)`) are recorded as unresolved.
 
 const SCRIPT_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'])
 const RESOLVABLE_EXTS = new Set([...SCRIPT_EXTS, '.json'])
+// Under `jsx`, these get parsed with JSX enabled. Excludes the .ts family: TypeScript's `<T>`
+// generics collide with JSX, so tsc/oxc reserve JSX for .tsx — JSX-in-TS belongs in a .tsx file.
+const JSX_EXTS = new Set(['.js', '.cjs', '.mjs'])
+// The inherently-JSX extensions (oxc parses them as JSX/TSX purely from the filename, no flag).
+// Scanned + carried only under `--jsx`: off by default the scanner treats them as opaque leaves,
+// so a bundle whose toolchain can't build JSX never silently ships .jsx/.tsx source. Under `--jsx`
+// they join SCRIPT_EXTS/RESOLVABLE_EXTS (see the constructor) so a reached .jsx/.tsx dependency
+// — e.g. a package whose React Native entry is src/index.tsx — is parsed and carried like any .ts.
+const JSX_FILE_EXTS = new Set(['.jsx', '.tsx'])
 
-// oxc-parser is a regular dependency, required lazily so non-JS bundlers (which
-// never reach getParser()) don't load the native parser.
+// Flow type syntax lives in the JS (non-TS) family; oxc parses TS natively, and running
+// flow-remove-types over a .ts/.tsx file would corrupt TS-only constructs, so --flow only strips
+// these. .jsx is included (it's JS + JSX, and can carry Flow types like .js); .tsx is not (it's
+// TypeScript). flow-remove-types preserves JSX, so a stripped .jsx re-parses under lang:jsx.
+const FLOW_EXTS = new Set(['.js', '.cjs', '.mjs', '.jsx'])
+
+// Required lazily so non-JS bundlers don't load the native oxc parser.
 let _parser
 function getParser() {
   _parser ??= createRequire(import.meta.url)('oxc-parser')
   return _parser
 }
 
-function packageType(file) {
-  const pkg = findPackageJSON(pathToFileURL(file).toString())
-  if (!pkg) return null
+// flow-remove-types is an optional dependency, loaded lazily and only under --flow: it strips
+// Flow type syntax down to plain JS before oxc (which parses JS/TS, not Flow) sees it. A missing
+// dep is an env error, so surface it with an actionable install hint rather than a bare resolve throw.
+let _flowRemoveTypes
+function getFlowRemoveTypes() {
+  if (_flowRemoveTypes) return _flowRemoveTypes
   try {
-    const type = JSON.parse(readFileSync(pkg, 'utf8')).type
-    return type === 'module' || type === 'commonjs' ? type : null
-  } catch {
-    return null
+    _flowRemoveTypes = createRequire(import.meta.url)('flow-remove-types')
+  } catch (cause) {
+    throw new Error(
+      "--flow needs the optional 'flow-remove-types' dependency; install it (e.g. `npm i flow-remove-types`)",
+      { cause }
+    )
   }
+  return _flowRemoveTypes
 }
 
-// Format per Node's own rules. TypeScript files get Node's type-stripping
-// formats ('module-typescript' / 'commonjs-typescript'), matching what Node's
-// load hook reports for them. For .js/.ts the module system comes from the
-// nearest package.json `type`; when that's absent (or unrecognized), Node
-// falls back to module-syntax detection, which requires the parse — null
-// signals "detect from syntax" to the caller.
+// classifyFormat is the shared name->format authority (static and runtime bundles must agree); it
+// returns null for the .js/.ts family whose module system comes from package.json `type` (null =
+// detect from syntax, signaled up as null).
 function formatForFile(file) {
-  const ext = extname(file)
-  if (ext === '.mjs') return 'module'
-  if (ext === '.cjs') return 'commonjs'
-  if (ext === '.json') return 'json'
-  if (ext === '.mts') return 'module-typescript'
-  if (ext === '.cts') return 'commonjs-typescript'
+  const format = classifyFormat(file)
+  if (format != null) return format
   const type = packageType(file)
   if (type === null) return null
-  const suffix = ext === '.ts' ? '-typescript' : ''
-  return `${type}${suffix}`
+  return `${type}${extname(file) === '.ts' ? '-typescript' : ''}`
 }
 
 function literalSpec(node) {
@@ -66,9 +71,7 @@ function literalSpec(node) {
   return null
 }
 
-// Walk the AST for require() and dynamic import() calls. ESM static imports and
-// re-exports are picked up separately from oxc-parser's `module.staticImports` /
-// `module.staticExports` -- much cheaper than walking the whole tree for them.
+// Walks require()/import() calls only; ESM static imports/re-exports come from oxc module records.
 function findCallSpecifiers(ast, push) {
   const visit = (node) => {
     if (!node || typeof node !== 'object') return
@@ -90,11 +93,8 @@ function findCallSpecifiers(ast, push) {
       if (spec != null) push({ kind: 'dynamic-import', spec })
       else push({ kind: 'dynamic-import', dynamic: true })
     } else if (node.type === 'TSImportEqualsDeclaration') {
-      // `import lib = require('./dep.cts')`: TS-only CJS import form. Node's
-      // type stripping refuses to run it (non-erasable syntax), but the
-      // dependency edge is real — record it like a require() so the bundle
-      // stays self-contained for transform-types users and external analysis.
-      // Qualified-name references (`import A = B.C`) carry no file edge.
+      // `import lib = require('./dep.cts')`: TS-only CJS import; record the real edge.
+      // Qualified-name form (`import A = B.C`) carries no file edge.
       if (node.moduleReference?.type === 'TSExternalModuleReference') {
         const spec = literalSpec(node.moduleReference.expression)
         if (spec != null) push({ kind: 'require', spec })
@@ -121,22 +121,33 @@ export class Scan {
   parseErrors = []
   entries = new Set()
 
-  // `conditions` is *additive* on top of the format-derived base set: ESM parents
-  // get ['node', 'import'] and CJS parents get ['node', 'require'], with any
-  // user-supplied conditions (e.g. 'browser', 'development') merged in. This
-  // matches what the runtime loader records when Node reports conditions for an
-  // edge -- different edges in the same scan can end up under different keys.
-  //
-  // `resolve` optionally replaces Node's own resolver with a custom one (the
-  // legacy-field resolver in resolve-fields.js drives `stasis bundle --mainFields`).
-  // It is called `(parentFile, specifier, conditions)` and returns
-  // `{ url } | { empty: true } | { builtin: true } | null` -- `empty` marks a
-  // browser/react-native `false` redirect (an empty-module stub the caller
-  // materialises), the rest mirror Node resolution. When set, it also handles
-  // builtins, so the built-in `isBuiltin` short-circuit is skipped.
-  constructor({ conditions = [], resolve = null } = {}) {
+  // `conditions` is additive on top of the edge-context base set. `resolve` optionally
+  // replaces Node's resolver (resolve-fields.js): returns `{ url } | { empty } | { builtin } | null`
+  // (`empty` = a browser/react-native `false` redirect) and owns builtin handling when set.
+  // `jsx` opts the .js/.cjs/.mjs family into JSX syntax (React Native's JSX-in-.js convention);
+  // off by default because oxc, like tsc, only auto-enables JSX for .jsx/.tsx by extension.
+  // `flow`: strip Flow type syntax from JS-family sources before parsing (see #scanFile).
+  // `resources` (a `parseResourcesOption` Set of extensions/filenames): reached files matching it
+  // are carried as opaque resources (bytes only) rather than rejected as un-carryable -- for graphs
+  // that aren't fully loadable in JS (e.g. Metro consuming .png/.svg assets).
+  constructor({ conditions = [], resolve = null, jsx = false, flow = false, resources = new Set() } = {}) {
     this.extraConditions = [...conditions]
     this.customResolve = resolve
+    this.jsx = jsx
+    this.flow = flow
+    this.resources = resources
+    // --jsx widens the script/resolvable extension sets to include .jsx/.tsx, so those files are
+    // parsed (not left as opaque leaves) and queued when reached. Off by default the base sets apply.
+    this.scriptExts = jsx ? new Set([...SCRIPT_EXTS, ...JSX_FILE_EXTS]) : SCRIPT_EXTS
+    this.resolvableExts = jsx ? new Set([...RESOLVABLE_EXTS, ...JSX_FILE_EXTS]) : RESOLVABLE_EXTS
+  }
+
+  // A reached file whose extension/filename is in the --resources allowlist: carried as an opaque
+  // resource (bytes only, no parse, no edges), not rejected as "a source bundle can't carry".
+  // classifyExtension returns 'resource' only for non-code names in the allowlist, so this never
+  // shadows a script/json extension (parseResourcesOption rejects code extensions).
+  #isResource(file) {
+    return this.resources.size > 0 && classifyExtension(file, this.resources) === 'resource'
   }
 
   walk(entries) {
@@ -156,29 +167,38 @@ export class Scan {
     return this
   }
 
-  // Match the runtime resolver's full condition set. Node 22 passes
-  // `['node', import|require, 'module-sync', 'node-addons']` to the resolve
-  // hook; if we omit any of these, a package whose `exports` map gates on the
-  // runtime-only conditions (e.g. `"module-sync": "./a.js", "import": "./b.js"`)
-  // resolves to a different file under static scan than under plain Node.
-  // Confirmed by reproducer with module-sync: plain node hits sync.js, static
-  // bundle loads with async.js -- silently runs different code.
-  #conditionsFor(format) {
-    const base = ['module', 'module-typescript'].includes(format)
-      ? ['node', 'import', 'module-sync', 'node-addons']
-      : ['node', 'require', 'module-sync', 'node-addons']
-    return new Set([...base, ...this.extraConditions])
+  // Must match the runtime resolver's condition set (omitting one resolves `exports`-gated
+  // packages to a different file) AND its order: the recorded key must equal the runtime
+  // hooks' string for exact lookups. Extras go where Node puts user conditions in each set.
+  #conditionSet(context) {
+    return context === 'import'
+      ? new Set(['node', 'import', 'module-sync', 'node-addons', ...this.extraConditions])
+      : new Set(['require', 'node', 'node-addons', ...this.extraConditions, 'module-sync'])
   }
 
-  // `recovered: false` means the parser crashed on this file and nothing was
-  // salvaged -- its edges are entirely unknown. `recovered: true` means oxc
-  // returned, but we discarded its partial module records (module-family
-  // formats only; see #scanFile).
+  // `recovered`: false = parser crashed, nothing salvaged; true = oxc returned but we
+  // discarded its partial module records (module-family only; see #scanFile).
   #recordParseError(url, format, message, recovered) {
     this.files.set(url, { format, edges: [], parseError: message })
     this.parseErrors.push({ url, format, message, recovered })
   }
 
+  // Strip Flow type syntax to plain JS via the optional flow-remove-types dep (resolved lazily; a
+  // missing dep is an env error and propagates). Only invoked as a parse fallback (see #scanFile),
+  // so plain-JS files never reach it. Returns the rewritten source, or null when the transform
+  // itself fails on this file -- the caller then keeps oxc's original parse error.
+  #stripFlow(src, file) {
+    const flowRemoveTypes = getFlowRemoveTypes()
+    try {
+      // `all: true` ignores the @flow/@noflow pragma (RN sources mix both); the transform blanks
+      // types with whitespace, so byte offsets and every import specifier are preserved.
+      return flowRemoveTypes(src, { all: true }).toString()
+    } catch (cause) {
+      console.warn(`[stasis] --flow: could not strip Flow types from ${file}; leaving it to oxc (${cause.message})`)
+      return null
+    }
+  }
+
   #scanFile(url, queue) {
     const file = fileURLToPath(url)
     const ext = extname(file)
@@ -186,56 +206,57 @@ export class Scan {
       this.files.set(url, { format: 'json', edges: [] })
       return
     }
-    if (!SCRIPT_EXTS.has(ext)) {
+    if (this.#isResource(file)) {
+      // Allowlisted asset: carry it as a resource with no parse and no edges. `resource: true` is
+      // the authoritative signal (both bundle builders key off it); the concrete format
+      // (resource vs resource:base64) is byte-derived by the builder, so leave it unset here.
+      this.files.set(url, { format: null, edges: [], resource: true })
+      return
+    }
+    if (!this.scriptExts.has(ext)) {
       this.files.set(url, { format: null, edges: [] })
       return
     }
 
-    // declared === null: typeless package, where Node decides .js/.ts by
-    // module-syntax detection — that needs the parse, so resolve it below.
+    // declared === null: typeless package; Node decides .js/.ts by syntax, resolved after parse.
     const declared = formatForFile(file)
     const src = readFileSync(file, 'utf8')
 
-    // Resolve the parser outside the per-file try below: a missing oxc-parser is
-    // an environment error, not a property of this file, so it must not be
-    // swallowed into a silent zero-edge leaf.
+    // Resolve the parser outside the try: a missing oxc-parser is an env error, not this
+    // file's — it must not be swallowed into a silent zero-edge leaf.
     const parser = getParser()
+    // oxc picks JS/TS + JSX from the filename; the .js family lands on plain JS (no JSX), so
+    // force the JSX variant when opted in (`--jsx`) to parse React Native's JSX-in-.js source.
+    const lang = this.jsx && JSX_EXTS.has(ext) ? 'jsx' : undefined
+    const parseOptions = (sourceType) => (lang ? { sourceType, lang } : { sourceType })
+    const baseSourceType = declared === null ? 'unambiguous'
+      : declared.startsWith('module') ? 'module' : 'script'
     let parsed
     try {
-      parsed = parser.parseSync(file, src, {
-        sourceType: declared === null ? 'unambiguous'
-          : declared.startsWith('module') ? 'module' : 'script',
-      })
+      parsed = parser.parseSync(file, src, parseOptions(baseSourceType))
     } catch (cause) {
       this.#recordParseError(url, declared, cause.message, false)
       return
     }
 
-    // Match Node's module-syntax detection for typeless packages: ESM syntax
-    // (import/export/import.meta) selects the module variant. Recording the
-    // commonjs variant here would make `--bundle=load` feed the source to the
-    // wrong translator, which throws instead of reparsing as ESM the way
-    // Node's on-disk loader does.
+    // Match Node's syntax detection for typeless packages: ESM syntax picks the module variant
+    // (mislabeling as commonjs makes `--bundle=load` feed the wrong translator). Only .ts takes the
+    // `-typescript` suffix; .jsx/.tsx deliberately land on plain module/commonjs (like a JSX-in-.js
+    // file) — they're bundler-transformed, keyed by extension in `stasis build`, not Node-strippable,
+    // so the "needs a JSX/TS transform" signal rides the .jsx/.tsx extension, not the format tag.
     let format = declared
       ?? `${parsed.module.hasModuleSyntax ? 'module' : 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
 
-    // oxc-parser recovers from syntax errors instead of throwing: it reports
-    // them in `parsed.errors` and returns whatever AST/module records it could
-    // salvage. (Warning/advice-severity diagnostics don't imply a broken parse
-    // and are not errors.)
+    // oxc recovers from syntax errors (reports them in parsed.errors) rather than throwing;
+    // Warning/Advice severities aren't real parse errors.
     const nonWarning = (p) => (p.errors ?? []).filter((e) => e.severity !== 'Warning' && e.severity !== 'Advice')
     let errors = nonWarning(parsed)
 
-    // Node's detector also counts top-level await as module syntax, which
-    // oxc's hasModuleSyntax does not flag: a typeless file whose ESM-ness
-    // rests on TLA alone parses here as a broken script while plain node runs
-    // it as a clean module. Mirror Node's parse-as-CJS-retry-as-ESM: when the
-    // detected-commonjs parse has errors but a module parse is clean, the
-    // module parse wins. Genuine CJS salvage cases (e.g. a top-level `return`
-    // guard) error under BOTH source types and stay on the script path.
+    // oxc's hasModuleSyntax misses top-level await, so a TLA-only ESM file parses here as a
+    // broken script; mirror Node by retrying as module and preferring a clean module parse.
     if (errors.length > 0 && declared === null && !format.startsWith('module')) {
       try {
-        const asModule = parser.parseSync(file, src, { sourceType: 'module' })
+        const asModule = parser.parseSync(file, src, parseOptions('module'))
         if (nonWarning(asModule).length === 0) {
           parsed = asModule
           format = `module${ext === '.ts' ? '-typescript' : ''}`
@@ -244,28 +265,41 @@ export class Scan {
       } catch { /* keep the script parse and its recorded errors */ }
     }
 
+    // --flow: oxc parses JS/TS but not Flow, so a Flow-typed .js/.cjs/.mjs file lands here with
+    // parse errors. Only now -- after a raw oxc parse actually failed -- strip Flow types and
+    // re-parse, so plain-JS files never pay the transform cost. Only the parse input is rewritten;
+    // the bundle stores the pristine on-disk source (State/buildResolvedJsBundle re-read it), so
+    // attestation still covers the real bytes. A clean re-parse replaces the errored one; otherwise
+    // we keep the original result so a genuine (non-Flow) parse error still surfaces.
+    if (errors.length > 0 && this.flow && FLOW_EXTS.has(ext)) {
+      const flowSrc = this.#stripFlow(src, file)
+      if (flowSrc !== null) {
+        try {
+          const asFlow = parser.parseSync(file, flowSrc, parseOptions(baseSourceType))
+          if (nonWarning(asFlow).length === 0) {
+            parsed = asFlow
+            format = declared ?? `${parsed.module.hasModuleSyntax ? 'module' : 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
+            errors = []
+          }
+        } catch { /* keep the original parse + its errors */ }
+      }
+    }
+
     let parseError
     if (errors.length > 0) {
       parseError = errors.map((e) => e.message).join('; ')
-      // A partially-parsed module file may be missing static link-time edges
-      // -- holes we can't enumerate -- so don't pretend we know its imports.
+      // A partially-parsed module file may be missing link-time edges we can't enumerate.
       if (format.startsWith('module')) {
         this.#recordParseError(url, format, parseError, true)
         return
       }
-      // Script (CJS) files: Node's module wrapper accepts code oxc rejects
-      // (e.g. a top-level `return` guard), and oxc's recovered AST keeps the
-      // require()/import() calls -- salvage the edges, record the error, and
-      // let callers decide how loud to be.
+      // Script (CJS) files: oxc's recovered AST still yields the require()/import() edges — salvage them.
       this.parseErrors.push({ url, format, message: parseError, recovered: true })
     }
 
     const specs = []
-    // ESM static imports + re-exports come from oxc's pre-extracted module info.
-    // Type-only edges (`import type ... from`, `export type ... from`) are
-    // erased before runtime and never loaded by Node; skip them so the bundle
-    // matches Node's actual load graph. A mixed `import { type A, B }` still
-    // loads, and bare side-effect imports have no entries — both are kept.
+    // Type-only edges (`import type`, `export type`) are erased before runtime — skip them so the
+    // bundle matches Node's load graph. Mixed (`{ type A, B }`) and bare side-effect imports are kept.
     if (parsed.module?.staticImports) {
       for (const imp of parsed.module.staticImports) {
         if (imp.entries.length > 0 && imp.entries.every((e) => e.isType)) continue
@@ -279,14 +313,20 @@ export class Scan {
         }
       }
     }
-    // require() and dynamic import() come from the AST.
     findCallSpecifiers(parsed.program, (s) => specs.push(s))
 
-    const conditions = this.#conditionsFor(format)
-    const key = condKey(conditions)
+    // The edge KIND picks the resolution context, not the parent's format: createRequire()d
+    // require() inside ESM resolves under REQUIRE conditions, literal import() inside CJS under
+    // IMPORT conditions -- the parent-format set baked the wrong `exports` branch into the bundle.
+    // The custom (legacy-field) resolver keeps the format set: bundlers don't split per edge.
+    const formatContext = ['module', 'module-typescript'].includes(format) ? 'import' : 'require'
     const req = createRequire(file)
     const edges = []
-    const specMap = new Map()
+    const specMaps = new Map() // condition key -> specifier -> child URL
+    const record = (key, spec, childURL) => {
+      if (!specMaps.has(key)) specMaps.set(key, new Map())
+      specMaps.get(key).set(spec, childURL)
+    }
 
     for (const s of specs) {
       if (s.dynamic) {
@@ -294,10 +334,11 @@ export class Scan {
         this.unresolved.push({ parentURL: url, kind: s.kind, reason: 'dynamic' })
         continue
       }
-      // Custom (legacy-field) resolver: it owns builtin handling and adds the
-      // `empty` outcome (a browser/react-native `false` redirect). An empty edge
-      // is recorded but neither queued (an empty module has no edges) nor counted
-      // as unresolved (it resolved -- to nothing).
+      const context = this.customResolve ? formatContext : (s.kind === 'require' ? 'require' : 'import')
+      const conditions = this.#conditionSet(context)
+      const key = condKey(conditions)
+      // Custom (legacy-field) resolver owns builtin handling and the `empty` outcome (browser/RN
+      // `false` redirect): an empty edge is recorded but neither queued nor counted as unresolved.
       if (this.customResolve) {
         const r = this.customResolve(file, s.spec, conditions)
         if (r?.builtin) {
@@ -306,8 +347,9 @@ export class Scan {
           edges.push({ ...s, empty: true })
         } else if (r?.url) {
           edges.push({ ...s, child: r.url })
-          specMap.set(s.spec, r.url)
-          if (RESOLVABLE_EXTS.has(extname(fileURLToPath(r.url)))) queue.push(r.url)
+          record(key, s.spec, r.url)
+          const childPath = fileURLToPath(r.url)
+          if (this.resolvableExts.has(extname(childPath)) || this.#isResource(childPath)) queue.push(r.url)
         } else {
           edges.push({ ...s, error: 'MODULE_NOT_FOUND' })
           this.unresolved.push({ parentURL: url, kind: s.kind, spec: s.spec, reason: 'MODULE_NOT_FOUND' })
@@ -322,16 +364,16 @@ export class Scan {
         const childPath = req.resolve(s.spec, { conditions })
         const childURL = pathToFileURL(childPath).toString()
         edges.push({ ...s, child: childURL })
-        specMap.set(s.spec, childURL)
+        record(key, s.spec, childURL)
         const childExt = extname(childPath)
-        if (RESOLVABLE_EXTS.has(childExt)) queue.push(childURL)
+        if (this.resolvableExts.has(childExt) || this.#isResource(childPath)) queue.push(childURL)
       } catch (cause) {
         edges.push({ ...s, error: cause.code ?? cause.message })
         this.unresolved.push({ parentURL: url, kind: s.kind, spec: s.spec, reason: cause.code ?? cause.message })
       }
     }
 
-    if (specMap.size > 0) {
+    for (const [key, specMap] of specMaps) {
       if (!this.imports.has(key)) this.imports.set(key, new Map())
       this.imports.get(key).set(url, specMap)
     }

package/src/cmd/extract.js

@@ -1,193 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
-import { brotliDecompressSync } from 'node:zlib'
-
-import { Bundle } from '@exodus/stasis-core/bundle'
-import { Lockfile } from '@exodus/stasis-core/lockfile'
-import { sha512integrity } from '@exodus/stasis-core/state-util'
-import { moduleFileKey } from '@exodus/stasis-core/util'
-
-const FILE_LOCK = 'stasis.lock.json'
-
-// Re-derive a Lockfile from an already-parsed Bundle. A bundle records each file's
-// content (UTF-8 source for code / 'resource', base64 for 'resource:base64'); a
-// lockfile records each file's SRI digest -- always taken over the same UTF-8
-// bytes the bundle stored (since the lockfile hashes the lockfile-visible content
-// without decoding). Both
-// share the same per-package bucket shape (name/version/files) plus the
-// entries/config metadata, so the conversion is just "hash each file's bytes"
-// while carrying everything else across verbatim.
-//
-// Requires a v1 bundle: v0 records no package name/version (Bundle.parse infers
-// buckets with null metadata), and Lockfile.serialize must attest both for
-// every node_modules bucket.
-//
-// The digest is taken over the same UTF-8 bytes we write to disk, so it equals
-// what `stasis run --lock=add` would record for the extracted tree and what
-// `stasis prune` recomputes when validating it.
-// Reject a 'resource:base64' content string that isn't canonical base64. Buffer.from
-// silently drops invalid characters and accepts non-canonical padding, so a tampered
-// bundle could ship `XXXX_invalid_chars==` and have the decoded bytes hash to whatever
-// it wanted -- the result would still self-consistently round-trip through `extract`
-// (decode → write → re-hash → match), but the on-disk file would diverge from what
-// any honest producer would have written. Fail closed at the schema-boundary by
-// requiring decode → re-encode to be a fixed point.
-function assertCanonicalBase64(content, file) {
-  const buf = Buffer.from(content, 'base64')
-  if (buf.toString('base64') !== content) {
-    throw new Error(`extract: non-canonical base64 in resource:base64 content for ${file}`)
-  }
-  return buf
-}
-
-export function lockfileFromBundle(bundle) {
-  const modules = new Map()
-  for (const [dir, { name, version, ecosystem, files }] of bundle.modules) {
-    const hashed = Object.create(null)
-    for (const [rel, content] of Object.entries(files)) {
-      // The lockfile records sha512 of each file's raw on-disk bytes -- the same
-      // hash `stasis run` produces. The bundle stores 'resource:base64' files as
-      // base64 text, so we decode back to the raw bytes before hashing; code and
-      // 'resource' files are stored as raw UTF-8 and hash identically either way
-      // (Node hashes a string as its UTF-8 bytes). assertCanonicalBase64 closes
-      // the lying-tag hole: a non-canonical base64 string is rejected outright.
-      const file = dir === '.' ? rel : `${dir}/${rel}`
-      const bytes = bundle.formats.get(file) === 'resource:base64'
-        ? assertCanonicalBase64(content, file)
-        : content
-      hashed[rel] = sha512integrity(bytes)
-    }
-    // Carry the dependency `ecosystem` across so the derived lockfile records the
-    // same ecosystem tag the bundle did.
-    modules.set(dir, ecosystem === undefined
-      ? { name, version, files: hashed }
-      : { name, version, ecosystem, files: hashed })
-  }
-  // Carry the bundle's resolution + format maps across so the derived lockfile
-  // attests them too (Bundle.parse already validated the paths) -- without them
-  // the lockfile would be a legacy bytes-only one, and a later frozen run
-  // against the same bundle would skip the resolution/format cross-checks.
-  return new Lockfile({
-    config: bundle.config,
-    entries: bundle.entries,
-    modules,
-    imports: bundle.imports,
-    formats: bundle.formats,
-  })
-}
-
-// Extract a brotli-compressed stasis code bundle (`stasis.code.br`) back onto
-// disk: write every bundled source to `output` (default: cwd), preserving its
-// project-relative path, and drop a matching `stasis.lock.json` alongside them.
-// The lockfile is derived from the bundle's own contents, so the extracted tree
-// validates against it out of the box (e.g. `stasis prune`). For legacy v0
-// bundles only the sources are extracted -- see the in-body comment.
-//
-// Returns `{ dir, files }` where `files` is the number of sources written
-// (the lockfile is not counted).
-export function extractCommand({ cwd = process.cwd(), bundleFile, output } = {}) {
-  if (!bundleFile) throw new Error('extract: a bundle file is required')
-  const bundleAbs = resolve(cwd, bundleFile)
-  if (!existsSync(bundleAbs)) throw new Error(`extract: bundle file not found: ${bundleAbs}`)
-
-  let bundle
-  try {
-    bundle = Bundle.parse(brotliDecompressSync(readFileSync(bundleAbs)).toString('utf-8'))
-  } catch (cause) {
-    // Bundle.parse rejects malformed shapes (e.g. a lockfile JSON fed by mistake,
-    // or a brotli blob that isn't a stasis bundle) with bare message-less asserts;
-    // wrap so the user sees which file failed instead of an empty error.
-    throw new Error(`extract: not a valid stasis bundle: ${bundleAbs}`, { cause })
-  }
-
-  // v0 legacy bundles record no package name/version (Bundle.parse infers buckets
-  // with null metadata), so no lockfile can be restored from them:
-  // Lockfile.serialize requires both for every node_modules bucket, and a
-  // null-metadata workspace entry would be rejected later by State.addFile's
-  // name/version cross-check. The sources themselves are still fully
-  // recoverable -- extract them and skip the lockfile, with a warning.
-  const withLockfile = bundle.version === Bundle.VERSION
-
-  const outDir = resolve(cwd, output ?? '.')
-  const outPrefix = outDir === sep ? outDir : `${outDir}${sep}`
-  const lockAbs = join(outDir, FILE_LOCK)
-
-  // Plan first, write later: validate every target path and confirm it stays
-  // inside outDir before touching disk, so a malformed bundle can't write a
-  // partial tree. Walk bundle.modules directly rather than the flattening
-  // `sources` getter, which silently last-wins when two buckets collapse to
-  // the same path. Treat the bundle as untrusted input and verify containment
-  // two ways: the resolved path must be BOTH non-escaping relative to outDir
-  // (no leading '..', not absolute -- `relative` returns an absolute path
-  // across Windows drives) AND lexically under `outDir/` (the trailing
-  // separator rejects sibling dirs that merely share outDir as a name prefix,
-  // e.g. `<outDir>-evil`). These checks are lexical only: pre-existing
-  // symlinks inside outDir are followed by the writes, so untrusted bundles
-  // belong in a fresh directory (see doc/extract.md).
-  const writes = []
-  const targets = new Set()
-  for (const [dir, { files }] of bundle.modules) {
-    for (const [rel, content] of Object.entries(files)) {
-      // A `directory` capture (`stasis run --fs`) keys a listing at the directory's
-      // OWN path; it isn't a file to write (its child files recreate the directory),
-      // and writing one would collide with those children at the file-vs-directory
-      // guard below. Skip it on disk -- the derived lockfile still attests its hash
-      // (lockfileFromBundle hashes every bundle entry, directory listings included).
-      // The format is looked up under the canonical key (moduleFileKey, so a
-      // package-ROOT listing's rel==='' resolves to the dir, not `${dir}/`); the
-      // write path below keeps the literal join, so a NON-directory empty file name
-      // still trips the non-canonical-path guard rather than being accepted here.
-      if (bundle.formats.get(moduleFileKey(dir, rel)) === 'directory') continue
-      const file = dir === '.' ? rel : `${dir}/${rel}`
-      if (typeof content !== 'string') throw new Error(`extract: bundle file content is not a string: ${file}`)
-      const abs = resolve(outDir, file)
-      const relToOut = relative(outDir, abs)
-      if (relToOut.startsWith('..') || isAbsolute(relToOut) || !abs.startsWith(outPrefix)) {
-        throw new Error(`extract: bundle path escapes output dir: ${file}`)
-      }
-      // Only canonical paths are accepted: a path that changes under the
-      // resolve+relative round-trip (mid-path '..' or '.', empty segments, an
-      // empty file name) is nothing State or the Solidity bundler ever emit,
-      // and writing it would desync the on-disk tree from the lockfile's
-      // recorded paths.
-      if (relToOut !== file) throw new Error(`extract: non-canonical bundle path: ${file}`)
-      if (targets.has(abs)) throw new Error(`extract: duplicate bundle path: ${file}`)
-      if (withLockfile && abs === lockAbs) {
-        throw new Error(`extract: bundle contains ${FILE_LOCK}, which would collide with the derived lockfile`)
-      }
-      targets.add(abs)
-      // Resources are decoded back to their original bytes: 'resource:base64' from
-      // base64 (rejected if non-canonical -- a tampered bundle can't ship lying
-      // padding/invalid-char base64), 'resource' (and code) is written as the raw
-      // UTF-8 string.
-      const data = bundle.formats.get(file) === 'resource:base64'
-        ? assertCanonicalBase64(content, file)
-        : content
-      writes.push([abs, data])
-    }
-  }
-  // A planned file may not also be needed as a parent directory of another --
-  // the mkdirSync/writeFileSync pair below would otherwise throw halfway
-  // through the writes.
-  for (const [abs] of writes) {
-    for (let d = dirname(abs); d.length > outDir.length; d = dirname(d)) {
-      if (targets.has(d)) {
-        throw new Error(`extract: bundle path used as both file and directory: ${relative(outDir, d)}`)
-      }
-    }
-  }
-  const lockText = withLockfile ? lockfileFromBundle(bundle).serialize() : null
-
-  for (const [abs, content] of writes) {
-    mkdirSync(dirname(abs), { recursive: true })
-    writeFileSync(abs, content)
-  }
-  mkdirSync(outDir, { recursive: true }) // for an empty bundle, where no write created it
-  if (withLockfile) writeFileSync(lockAbs, lockText)
-
-  console.warn(`[stasis] Extracted ${writes.length} file(s)${withLockfile ? ` and ${FILE_LOCK}` : ''} to ${outDir}`)
-  if (!withLockfile) {
-    console.warn(`[stasis] Warning: legacy v0 bundle records no package name/version, so ${FILE_LOCK} can not be restored and was not written`)
-  }
-  return { dir: outDir, files: writes.length }
-}