@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/function-bundle-recovery.ts

@@ -0,0 +1,775 @@
+import { posix } from 'node:path'
+
+import { fromOutsidePath } from '../function-outside-imports'
+
+/**
+ * Modules a pulled Function imports that its source archive lacks, recovered
+ * from the bundle the version runs.
+ *
+ * A Function deployed from its folder before deploys kept the files it
+ * imports from beside it (`../../shared/eligibility`) has a source archive
+ * without them, so the pull cannot build it. Its bundle still holds their
+ * code: Bun scope-hoists every module into one file and marks where each
+ * begins with its path (`// ../shared/eligibility.ts`, relative to wherever
+ * the author built it). This cuts those modules back out, as JavaScript, at
+ * the path the import expects.
+ *
+ * What comes back is the bundled JavaScript, not the original TypeScript:
+ * types are gone, and so is anything the Function did not use (the bundler
+ * drops it). Each module is written as `<path>.js` beside a `<path>.d.ts`
+ * typing every export `any`: Bun picks the `.js`, so the Function builds and
+ * runs; TypeScript picks the `.d.ts` and never checks the `.js`. A `.ts` with
+ * `// @ts-nocheck` was the alternative, and it typechecks worse: a parameter
+ * the source marked optional (`opts?: …`) comes back required, and an
+ * object's inferred shape is narrower than its declared type.
+ *
+ * Neither gives the types back. A caller that leaned on them (an unannotated
+ * callback over a recovered function's result, an arrow assigned to a
+ * recovered function type) fails `noImplicitAny` until the original source
+ * replaces the recovered files; while the files are as pulled, `local check`
+ * counts those errors as inherited.
+ *
+ * A module is left out, with the reason, when the bundle cannot give it back
+ * whole: no module markers (built minified, or by another tool), a name an
+ * importer needs that the bundler inlined or dropped (an enum's members are
+ * inlined where they are used), code wrapped as CommonJS, or a name it uses
+ * from a package or a file the project does not hold.
+ */
+
+/** One top-level statement of a bundle, with the names it declares at the top level. */
+export interface BundleStatement {
+  text: string
+  declares: string[]
+}
+
+export interface BundleSection {
+  /** The path Bun marked it with, relative to where the bundle was built. */
+  marker: string
+  statements: BundleStatement[]
+  text: string
+}
+
+export interface ParsedBundle {
+  /** The bundler's own helpers (`__export`, `__toESM`, …) and hoisted imports, before the first module. */
+  prelude: BundleStatement[]
+  sections: BundleSection[]
+}
+
+/** A recovered module from one or more bundles, before it is written as files. */
+export interface RecoveredModule {
+  /** Project path without extension: `functions/shared/staff-eligibility` (or `…/util/index`). */
+  path: string
+  /** `staff-availability@v3`: the bundles it came from. */
+  from: string[]
+  statements: BundleStatement[]
+  /** Export name → the bundle's local name. */
+  exports: Map<string, string>
+  /** Names an importer uses only as types: declared `any`. */
+  types: Set<string>
+  /** Local name → where it comes from (another recovered module, or a project file), by project path without extension. */
+  imports: Map<string, { from: string; name: string }>
+}
+
+export interface RecoveryResult {
+  modules: RecoveredModule[]
+  /** Project path without extension → why it could not be recovered. */
+  failed: Record<string, string>
+  /**
+   * What a test file imports that the bundle does not hold (it is built from
+   * the entry, not the tests), by recovered module: the Function still builds
+   * and runs, and that test needs the original source.
+   */
+  testOnly: Record<string, string[]>
+}
+
+// ---------------------------------------------------------------------------
+// Tokens: enough of JavaScript to find top-level statements and what they declare.
+
+interface Tok {
+  type: 'id' | 'num' | 'str' | 'punct' | 'regex' | 'tpl'
+  value: string
+  start: number
+  end: number
+  line: number
+  /** The first token on its line, at column 0. */
+  col0: boolean
+}
+
+const REGEX_AFTER = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await'])
+const PUNCT = ['>>>=', '...', '===', '!==', '**=', '<<=', '>>=', '>>>', '&&=', '||=', '??=', '=>', '==', '!=', '<=', '>=', '&&', '||', '??', '?.', '++', '--', '+=', '-=', '*=', '/=', '%=', '&=', '|=', '^=', '**', '<<', '>>']
+const ID_START = /[A-Za-z_$\u0080-￿]/
+const ID_PART = /[\w$\u0080-￿]/
+
+export function tokenize(src: string): Tok[] {
+  const toks: Tok[] = []
+  // Brace depth at which each open `${` began, so its `}` resumes the template.
+  const tpl: number[] = []
+  let braces = 0
+  let line = 0
+  let lineStart = true
+  let col0 = true
+  let i = 0
+  const push = (type: Tok['type'], start: number, end: number) => {
+    toks.push({ type, value: src.slice(start, end), start, end, line, col0: lineStart && col0 })
+    lineStart = false
+  }
+  const template = (from: number): number => {
+    // From just after '`' or a resuming '}': to the closing '`' (returns after it) or a `${`.
+    let j = from
+    while (j < src.length) {
+      const c = src[j]!
+      if (c === '\\') { j += 2; continue }
+      if (c === '\n') line++
+      if (c === '`') return j + 1
+      if (c === '$' && src[j + 1] === '{') {
+        tpl.push(braces)
+        braces++
+        return j + 2
+      }
+      j++
+    }
+    return j
+  }
+  while (i < src.length) {
+    const c = src[i]!
+    if (c === '\n') { line++; lineStart = true; col0 = true; i++; continue }
+    if (c === ' ' || c === '\t' || c === '\r') { if (lineStart) col0 = false; i++; continue }
+    if (c === '/' && src[i + 1] === '/') { while (i < src.length && src[i] !== '\n') i++; continue }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2)
+      const stop = end < 0 ? src.length : end + 2
+      for (let k = i; k < stop; k++) if (src[k] === '\n') line++
+      i = stop
+      continue
+    }
+    const start = i
+    if (c === '"' || c === "'") {
+      i++
+      while (i < src.length && src[i] !== c && src[i] !== '\n') i += src[i] === '\\' ? 2 : 1
+      i++
+      push('str', start, i)
+      continue
+    }
+    if (c === '`') {
+      i = template(i + 1)
+      push('tpl', start, i)
+      continue
+    }
+    if (c === '}' && tpl.length && braces - 1 === tpl[tpl.length - 1]) {
+      tpl.pop()
+      braces--
+      i = template(i + 1)
+      push('tpl', start, i)
+      continue
+    }
+    if (ID_START.test(c) || (c === '#' && ID_START.test(src[i + 1] ?? ''))) {
+      i++
+      while (i < src.length && ID_PART.test(src[i]!)) i++
+      push('id', start, i)
+      continue
+    }
+    if (/\d/.test(c) || (c === '.' && /\d/.test(src[i + 1] ?? ''))) {
+      i++
+      while (i < src.length && (/[\w.]/.test(src[i]!) || ((src[i] === '+' || src[i] === '-') && /[eE]/.test(src[i - 1]!) && !/^0[xX]/.test(src.slice(start, i))))) i++
+      push('num', start, i)
+      continue
+    }
+    if (c === '/') {
+      const prev = toks[toks.length - 1]
+      const regex = !prev || (prev.type === 'punct' && ![')', ']', '}'].includes(prev.value)) || (prev.type === 'id' && REGEX_AFTER.has(prev.value))
+      if (regex) {
+        i++
+        let cls = false
+        while (i < src.length && src[i] !== '\n') {
+          const r = src[i]!
+          if (r === '\\') { i += 2; continue }
+          if (r === '[') cls = true
+          else if (r === ']') cls = false
+          else if (r === '/' && !cls) break
+          i++
+        }
+        i++
+        while (i < src.length && ID_PART.test(src[i]!)) i++
+        push('regex', start, i)
+        continue
+      }
+    }
+    const multi = PUNCT.find((p) => src.startsWith(p, i) && !(p === '?.' && /\d/.test(src[i + 2] ?? '')))
+    i += multi ? multi.length : 1
+    if (c === '{') braces++
+    else if (c === '}') braces--
+    push('punct', start, i)
+  }
+  return toks
+}
+
+const OPEN = new Set(['(', '[', '{'])
+const CLOSE = new Set([')', ']', '}'])
+/** After a `}` at the top level, a statement goes on only with one of these at the start of the next line. */
+const CONTINUES = new Set([';', ')', ']', '}', ',', '.', '?.', ':', '?', '=', '=>', '&&', '||', '??', '+', '-', '*', '/', '%'])
+
+/** The top-level statements of a piece of bundled JavaScript. */
+export function statementsOf(src: string): BundleStatement[] {
+  const toks = tokenize(src)
+  const out: BundleStatement[] = []
+  let depth = 0
+  let begin = 0
+  const close = (end: number) => {
+    const part = toks.slice(begin, end + 1)
+    if (part.length) out.push({ text: src.slice(part[0]!.start, part[part.length - 1]!.end), declares: declaredBy(part) })
+    begin = end + 1
+  }
+  for (let k = 0; k < toks.length; k++) {
+    const t = toks[k]!
+    if (t.type === 'punct' && OPEN.has(t.value)) depth++
+    else if (t.type === 'punct' && CLOSE.has(t.value)) depth--
+    else if (t.type === 'tpl' && t.value.endsWith('${')) depth++
+    if (t.type === 'tpl' && t.value.startsWith('}')) depth--
+    if (depth !== 0) continue
+    if (t.type === 'punct' && t.value === ';') close(k)
+    else if (t.type === 'punct' && t.value === '}') {
+      const next = toks[k + 1]
+      if (!next || (next.line > t.line && next.col0 && !(next.type === 'punct' && CONTINUES.has(next.value)))) close(k)
+    }
+  }
+  if (begin < toks.length) close(toks.length - 1)
+  return out
+}
+
+/** The names a top-level statement declares. */
+function declaredBy(toks: Tok[]): string[] {
+  const first = toks[0]
+  if (!first || first.type !== 'id') return []
+  const at = (k: number) => toks[k]
+  if (first.value === 'import' && at(1)?.value !== '(' && at(1)?.value !== '.') {
+    const names: string[] = []
+    let entry: string[] = []
+    const flush = () => {
+      if (entry.length && entry[0] !== 'type') names.push(entry[entry.length - 1]!)
+      entry = []
+    }
+    for (let k = 1; k < toks.length; k++) {
+      const t = toks[k]!
+      if (t.type === 'str' || (t.type === 'id' && t.value === 'from')) break
+      if (t.type === 'id') entry.push(t.value)
+      else if (t.value === ',' || t.value === '{' || t.value === '}') flush()
+    }
+    flush()
+    return names.filter((n) => n !== 'as' && n !== '*')
+  }
+  let k = 0
+  if (first.value === 'async' && at(1)?.value === 'function') k = 1
+  if (at(k)?.value === 'function') {
+    const name = at(k + 1)?.value === '*' ? at(k + 2) : at(k + 1)
+    return name?.type === 'id' ? [name.value] : []
+  }
+  if (first.value === 'class') return at(1)?.type === 'id' ? [at(1)!.value] : []
+  if (first.value !== 'var' && first.value !== 'let' && first.value !== 'const') return []
+  // Declarators: a name or a pattern, each at the top of the statement, separated by commas.
+  const names: string[] = []
+  let depth = 0
+  let expectBinding = true
+  for (let k2 = 1; k2 < toks.length; k2++) {
+    const t = toks[k2]!
+    if (expectBinding && depth === 0) {
+      if (t.type === 'id') { names.push(t.value); expectBinding = false; continue }
+      if (t.value === '{' || t.value === '[') {
+        // A destructuring pattern: its bindings are the names not followed by `:` and not after `=`.
+        let d = 0
+        let j = k2
+        for (; j < toks.length; j++) {
+          const p = toks[j]!
+          if (OPEN.has(p.value)) d++
+          else if (CLOSE.has(p.value)) { d--; if (d === 0) break }
+          else if (p.type === 'id' && toks[j + 1]?.value !== ':' && toks[j - 1]?.value !== '=' && toks[j - 1]?.value !== '.' ) names.push(p.value)
+        }
+        k2 = j
+        expectBinding = false
+        continue
+      }
+    }
+    if (t.type === 'punct' && OPEN.has(t.value)) depth++
+    else if (t.type === 'punct' && CLOSE.has(t.value)) depth--
+    else if (t.type === 'tpl' && t.value.endsWith('${')) depth++
+    if (t.type === 'tpl' && t.value.startsWith('}')) depth--
+    if (depth === 0 && t.value === ',') expectBinding = true
+  }
+  return names
+}
+
+// ---------------------------------------------------------------------------
+// The bundle.
+
+/** `// ../shared/eligibility.ts`: where Bun says a module begins. Its own `// @bun` header is not one. */
+const MARKER = /^\/\/ ([^@\s][^\n]*\.(?:[cm]?[jt]sx?|json))$/
+
+export function parseBundle(bundle: string): ParsedBundle {
+  const lines = bundle.split('\n')
+  const prelude: string[] = []
+  const sections: { marker: string; lines: string[] }[] = []
+  for (const line of lines) {
+    const m = MARKER.exec(line)
+    if (m) sections.push({ marker: m[1]!, lines: [] })
+    else if (sections.length) sections[sections.length - 1]!.lines.push(line)
+    else prelude.push(line)
+  }
+  return {
+    prelude: statementsOf(prelude.join('\n')),
+    sections: sections.map((s) => {
+      const text = s.lines.join('\n')
+      return { marker: s.marker, text, statements: statementsOf(text) }
+    }),
+  }
+}
+
+const PROBE = '__frontera_probe__'
+
+/**
+ * Which of `names` a piece of JavaScript uses as free variables: Bun's own
+ * parser decides, by importing them all and keeping only those the code
+ * reads (`trimUnusedImports`). A parameter or local of the same name shadows
+ * a top-level one in another module, and only a real scope analysis can tell
+ * the two apart.
+ */
+export function freeNames(code: string, names: Iterable<string>, loader: 'js' | 'ts' = 'js'): Set<string> {
+  const list = [...new Set(names)].filter((n) => /^[A-Za-z_$][\w$]*$/.test(n))
+  if (!list.length) return new Set()
+  const out = new Bun.Transpiler({ loader, trimUnusedImports: true }).transformSync(`import { ${list.join(', ')} } from "${PROBE}";\n${code}`)
+  const m = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*"${PROBE}"`).exec(out)
+  return new Set(m ? m[1]!.split(',').map((s) => s.trim().split(/\s+as\s+/)[0]!).filter(Boolean) : [])
+}
+
+/** An import or re-export in a source file: what it names, from where. */
+interface ImportUse {
+  specifier: string
+  /** Imported names (`default` for a default import); `*` for a namespace, with its local name. */
+  names: { imported: string; local: string; type: boolean }[]
+  namespace?: string
+  /** `export * from`. */
+  all?: boolean
+}
+
+/** The import and re-export statements of TypeScript source, with each name and whether it is type-only. */
+export function importsOf(source: string): ImportUse[] {
+  const out: ImportUse[] = []
+  const re = /\b(import|export)\s+(type\s+)?([\w$*{}\s,]*?)\s*from\s*['"]([^'"]+)['"]/g
+  for (const m of source.matchAll(re)) {
+    const typeAll = !!m[2]
+    const clause = m[3]!.trim()
+    const use: ImportUse = { specifier: m[4]!, names: [] }
+    if (m[1] === 'export' && clause === '*') use.all = true
+    const ns = /\*\s*as\s+([\w$]+)/.exec(clause)
+    if (ns) use.namespace = ns[1]!
+    const braces = /\{([^}]*)\}/.exec(clause)
+    const before = clause.replace(/\{[^}]*\}/, '').replace(/\*\s*as\s+[\w$]+/, '').replace(/,/g, ' ').trim()
+    if (m[1] === 'import' && before && /^[\w$]+$/.test(before)) use.names.push({ imported: 'default', local: before, type: typeAll })
+    for (const part of braces ? braces[1]!.split(',') : []) {
+      const p = part.trim()
+      if (!p) continue
+      const type = typeAll || /^type\s+/.test(p)
+      const [imported, local] = p.replace(/^type\s+/, '').split(/\s+as\s+/).map((s) => s.trim())
+      use.names.push({ imported: imported!, local: local ?? imported!, type })
+    }
+    out.push(use)
+  }
+  return out
+}
+
+/** The names an import of `specifier` in TypeScript `source` uses as values (the rest are types, or unused). */
+function valueImports(source: string, specifier: string): Set<string> {
+  let js: string
+  try {
+    js = new Bun.Transpiler({ loader: 'ts', trimUnusedImports: true }).transformSync(source)
+  } catch {
+    return new Set()
+  }
+  const out = new Set<string>()
+  for (const use of importsOf(js)) {
+    if (use.specifier !== specifier) continue
+    for (const n of use.names) out.add(n.imported)
+    if (use.namespace) out.add('*')
+  }
+  // `export … from` is a value re-export the transpiler keeps as is.
+  return out
+}
+
+/** Bun's name for a module's anonymous default export: `<file name>_default`. */
+function defaultName(path: string): string {
+  const base = posix.basename(path).replace(/\.[^.]+$/, '')
+  const name = (base === 'index' ? posix.basename(posix.dirname(path)) : base).replace(/[^\w$]/g, '_')
+  return `${/^\d/.test(name) ? `_${name}` : name}_default`
+}
+
+/** `level` in a module whose bundle renamed it `level2` to avoid another module's `level`. */
+function bundleNameIn(declared: ReadonlySet<string>, name: string): string | null {
+  if (declared.has(name)) return name
+  const variants = [...declared].filter((d) => d.startsWith(name) && /^\d+$/.test(d.slice(name.length)))
+  return variants.length === 1 ? variants[0]! : null
+}
+
+const CODE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.js', '.mjs', '.cjs', '/index.ts', '/index.tsx', '/index.js']
+
+export interface RecoverInput {
+  slug: string
+  version: number | string
+  bundle: string
+  /** The Function's folder in the project: `functions/staff-availability`. */
+  folder: string
+  /** Its source archive, by archive path (files from beside the folder under `frontera-imports/`). */
+  files: ReadonlyMap<string, string>
+  /** The archive path of its entry (`src/index.ts`). */
+  entry: string
+  /** What its code imports that the archive lacks, by path from the folder without extension (`../shared/eligibility`). */
+  missing: string[]
+  /** Whether a pull may write a recovered module at this project path (without extension). */
+  writable: (projectPath: string) => boolean
+  /** Source the pull holds from elsewhere (another Function's archive), by project path without extension: imported, never recovered. */
+  elsewhere?: ReadonlyMap<string, string>
+}
+
+/**
+ * Recover the missing modules (and any module they import that the archive
+ * also lacks) from one Function's bundle.
+ */
+export function recoverFromBundle(input: RecoverInput): RecoveryResult {
+  const failed: Record<string, string> = {}
+  const project = (fromFolder: string) => posix.normalize(posix.join(input.folder, fromFolder))
+  const fail = (paths: string[], why: string): RecoveryResult => {
+    for (const p of paths) failed[project(p)] = why
+    return { modules: [], failed, testOnly: {} }
+  }
+  const parsed = parseBundle(input.bundle)
+  if (!parsed.sections.length) return fail(input.missing, 'its deployed bundle has no module markers to cut the file back out of (it was built minified, or by another tool)')
+
+  // Where the bundle was built from, found by the entry's marker: the last module, as Bun orders them.
+  const located = locateMarkers(parsed, input.entry)
+  if (!located) return fail(input.missing, `its deployed bundle has no module marked as its entry (${input.entry})`)
+  const markerOf: (fromFolder: string) => string = located
+
+  const bySection = new Map(parsed.sections.map((s, i) => [s.marker, i]))
+  // Every section's project path (without extension), when it is the Function's own or a file beside it.
+  const archiveOf = new Map<number, { project: string; content: string }>()
+  for (const [archivePath, content] of input.files) {
+    const fromFolder = fromOutsidePath(archivePath) ?? archivePath
+    const at = bySection.get(markerOf(fromFolder))
+    if (at !== undefined) archiveOf.set(at, { project: project(fromFolder).replace(/\.[^./]+$/, ''), content })
+  }
+  const sectionFor = (fromFolder: string): { index: number; ext: string } | null => {
+    for (const ext of CODE_EXTENSIONS) {
+      const at = bySection.get(markerOf(`${fromFolder}${ext}`))
+      if (at !== undefined) return { index: at, ext }
+    }
+    return null
+  }
+
+  const declaredIn = parsed.sections.map((s) => new Set(s.statements.flatMap((st) => st.declares)))
+  const preludeBy = new Map<string, number>()
+  parsed.prelude.forEach((st, i) => st.declares.forEach((n) => preludeBy.set(n, i)))
+  const sectionBy = new Map<string, number>()
+  declaredIn.forEach((names, i) => names.forEach((n) => sectionBy.set(n, i)))
+
+  // The modules to recover, by section; grows with what they import that the archive lacks.
+  const recovering = new Map<number, string>()
+  const queue: number[] = []
+  const want = (index: number, path: string) => {
+    if (recovering.has(index)) return
+    recovering.set(index, path)
+    queue.push(index)
+  }
+  for (const m of input.missing) {
+    const found = sectionFor(m)
+    if (!found) { failed[project(m)] = `its deployed bundle holds no module at ${m}${CODE_EXTENSIONS.slice(0, 3).join(', ')}, …`; continue }
+    const path = project(m) + (found.ext.startsWith('/index') ? '/index' : '')
+    if (!input.writable(path)) { failed[project(m)] = 'a pull doesn’t write into that folder'; continue }
+    want(found.index, path)
+  }
+
+  const modules = new Map<number, RecoveredModule>()
+  const reasons = new Map<number, string>()
+  const label = `${input.slug}@v${String(input.version).replace(/^v/, '')}`
+  while (queue.length) {
+    const index = queue.shift()!
+    try {
+      recoverSection(index)
+    } catch (err) {
+      reasons.set(index, `its code in the deployed bundle couldn’t be read back (${(err as Error).message.split('\n')[0]})`)
+    }
+  }
+  function recoverSection(index: number): void {
+    const section = parsed.sections[index]!
+    const path = recovering.get(index)!
+    const own = declaredIn[index]!
+    const wrapped = [...own].find((n) => /^(require|init)_/.test(n) && /__(commonJS|esm)\(/.test(section.text))
+    if (wrapped) { reasons.set(index, 'its deployed bundle holds it wrapped as a CommonJS module, which can’t be cut back out'); return }
+    const mod: RecoveredModule = { path, from: [label], statements: [], exports: new Map(), types: new Set(), imports: new Map() }
+    // The bundler's helpers it uses, and those they use, in the bundle's order.
+    const helpers = new Set<number>()
+    const pull = (code: string) => {
+      for (const n of freeNames(code, [...preludeBy.keys()].filter((k) => code.includes(k)))) {
+        const at = preludeBy.get(n)!
+        if (helpers.has(at)) continue
+        helpers.add(at)
+        pull(parsed.prelude[at]!.text)
+      }
+    }
+    pull(section.text)
+    mod.statements.push(...[...helpers].sort((a, b) => a - b).map((at) => parsed.prelude[at]!))
+    mod.statements.push(...section.statements)
+    const local = new Set([...own, ...[...helpers].flatMap((at) => parsed.prelude[at]!.declares)])
+    // What it uses from the other modules of the bundle.
+    const candidates = [...sectionBy.keys()].filter((n) => !local.has(n) && sectionBy.get(n) !== index && new RegExp(`(^|[^\\w$.])${n.replace(/\$/g, '\\$')}(?![\\w$])`).test(section.text))
+    for (const name of freeNames(section.text, candidates)) {
+      const at = sectionBy.get(name)!
+      const other = parsed.sections[at]!
+      const fromFolderOther = archiveOf.has(at) ? null : folderPathOf(markerOf, other.marker)
+      const heldPath = fromFolderOther ? project(fromFolderOther.replace(/\.[^./]+$/, '')) : null
+      const held = heldPath ? input.elsewhere?.get(heldPath) : undefined
+      const file = archiveOf.get(at) ?? (held !== undefined ? { project: heldPath!, content: held } : undefined)
+      if (file) {
+        const exported = new Set(new Bun.Transpiler({ loader: 'ts' }).scan(file.content).exports)
+        const original = exported.has(name) ? name : name === defaultName(other.marker) && exported.has('default') ? 'default' : [...exported].find((e) => name.startsWith(e) && /^\d+$/.test(name.slice(e.length)))
+        if (!original) { reasons.set(index, `it uses \`${name}\` from ${file.project}, which that file doesn’t export`); break }
+        mod.imports.set(name, { from: file.project, name: original })
+        continue
+      }
+      if (/(^|\/)node_modules\//.test(other.marker)) { reasons.set(index, `it uses \`${name}\` from the package ${packageOf(other.marker)}, which its deployed bundle holds inlined`); break }
+      // Another module from beside the folder that the archive lacks too.
+      const otherPath = heldPath
+      if (!otherPath || otherPath.startsWith('../') || !input.writable(otherPath)) { reasons.set(index, `it uses \`${name}\` from ${other.marker}, which the project doesn’t hold`); break }
+      want(at, otherPath)
+      mod.imports.set(name, { from: otherPath, name })
+    }
+    if (!reasons.has(index)) modules.set(index, mod)
+  }
+
+  // What importers in the archive need of each recovered module.
+  const testOnly: Record<string, string[]> = {}
+  const byPath = new Map([...modules.values()].map((m) => [m.path, m]))
+  const indexOf = new Map([...modules.entries()].map(([i, m]) => [m.path, i]))
+  for (const [archivePath, content] of input.files) {
+    if (!/\.(ts|tsx|mts|js|mjs)$/.test(archivePath) || archivePath.endsWith('.d.ts')) continue
+    const fromFolder = fromOutsidePath(archivePath) ?? archivePath
+    for (const use of importsOf(content)) {
+      if (!use.specifier.startsWith('.')) continue
+      const target = project(posix.join(posix.dirname(fromFolder), use.specifier)).replace(/\.(ts|tsx|js|mjs)$/, '')
+      const mod = byPath.get(target) ?? byPath.get(`${target}/index`)
+      if (!mod) continue
+      const index = indexOf.get(mod.path)!
+      if (reasons.has(index)) continue
+      const declared = declaredIn[index]!
+      const values = valueImports(content, use.specifier)
+      const need = (imported: string) => {
+        const name = imported === 'default'
+          ? bundleNameIn(declared, defaultName(parsed.sections[index]!.marker))
+          : bundleNameIn(declared, imported)
+        if (name) { mod.exports.set(imported, name); return true }
+        // A test imports from the module too, but the bundle was built from the entry: what only a
+        // test uses was never in it. That costs the test, not the Function.
+        if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(archivePath)) {
+          testOnly[mod.path] = [...new Set([...(testOnly[mod.path] ?? []), imported])].sort()
+          return true
+        }
+        reasons.set(index, imported === 'default'
+          ? `its default export isn’t named in the deployed bundle (imported by ${posix.normalize(posix.join(input.folder, fromFolder))})`
+          : `\`${imported}\` isn’t in the deployed bundle: the bundler inlined or dropped it (an enum’s members and some constants are inlined where they are used), so ${posix.normalize(posix.join(input.folder, fromFolder))} can’t import it`)
+        return false
+      }
+      if (use.all) { for (const n of declared) if (!n.startsWith('__')) mod.exports.set(n, n); continue }
+      if (use.namespace && values.has('*')) {
+        const listed = namespaceExports(parsed.sections[index]!.text)
+        const members = listed ? [...listed.keys()] : [...content.matchAll(new RegExp(`\\b${use.namespace.replace(/\$/g, '\\$')}\\s*\\.\\s*([A-Za-z_$][\\w$]*)`, 'g'))].map((m) => m[1]!)
+        for (const n of new Set(members)) if (!need(n)) break
+      }
+      for (const n of use.names) {
+        if (n.type || !values.has(n.imported)) { mod.types.add(n.imported); continue }
+        if (!need(n.imported)) break
+      }
+    }
+  }
+
+  // A module that needs one that failed fails too.
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const [index, mod] of modules) {
+      if (reasons.has(index)) continue
+      const broken = [...mod.imports.values()].find((i) => {
+        const at = indexOf.get(i.from)
+        return at !== undefined && reasons.has(at)
+      })
+      if (broken) { reasons.set(index, `it needs ${broken.from}, which couldn’t be recovered`); changed = true }
+    }
+  }
+
+  // Each module exports what its recovered siblings use of it.
+  for (const [index, mod] of modules) {
+    if (reasons.has(index)) continue
+    for (const [localName, imp] of mod.imports) {
+      const target = byPath.get(imp.from)
+      if (!target) continue
+      const exported = [...target.exports].find(([, l]) => l === imp.name)
+      if (exported) mod.imports.set(localName, { from: imp.from, name: exported[0] })
+      else target.exports.set(imp.name, imp.name)
+    }
+  }
+  for (const [index, why] of reasons) failed[recovering.get(index)!.replace(/\/index$/, '')] = why
+  const kept = [...modules.entries()].filter(([i]) => !reasons.has(i)).map(([, m]) => m)
+  return { modules: kept, failed, testOnly: Object.fromEntries(Object.entries(testOnly).filter(([path]) => kept.some((m) => m.path === path))) }
+}
+
+/** `__export(exports_x, { level: () => level2 })`: a module's namespace as the bundle lists it, export → local. */
+function namespaceExports(text: string): Map<string, string> | null {
+  const m = /__export\(\s*exports_[\w$]+\s*,\s*\{([\s\S]*?)\}\s*\)/.exec(text)
+  if (!m) return null
+  const out = new Map<string, string>()
+  for (const e of m[1]!.matchAll(/([\w$]+)\s*:\s*\(\)\s*=>\s*([\w$]+)/g)) out.set(e[1]!, e[2]!)
+  return out
+}
+
+function packageOf(marker: string): string {
+  const rest = marker.slice(marker.lastIndexOf('node_modules/') + 'node_modules/'.length).split('/')
+  return rest[0]!.startsWith('@') ? `${rest[0]}/${rest[1]}` : rest[0]!
+}
+
+/**
+ * How the bundle's markers name a file, given its path from the Function's
+ * folder: found from the entry's marker. Built in the folder (`src/index.ts`),
+ * above it (`functions/x/src/index.ts`, `../../x/src/index.ts`) or inside it
+ * (`index.ts`, from `src/`).
+ */
+function locateMarkers(parsed: ParsedBundle, entry: string): ((fromFolder: string) => string) | null {
+  const markers = parsed.sections.map((s) => s.marker)
+  const ordered = [markers[markers.length - 1]!, ...markers.slice(0, -1).reverse()].filter((m) => !/(^|\/)node_modules\//.test(m))
+  for (const marker of ordered) {
+    if (marker === entry || marker.endsWith(`/${entry}`)) {
+      const prefix = marker.slice(0, marker.length - entry.length)
+      return (fromFolder) => posix.normalize(`${prefix}${fromFolder}`)
+    }
+  }
+  // Built from inside the folder: the entry's marker is the tail of its path.
+  const parts = entry.split('/')
+  for (let k = 1; k < parts.length; k++) {
+    const tail = parts.slice(k).join('/')
+    if (!ordered.includes(tail)) continue
+    const inside = parts.slice(0, k).join('/')
+    const root = '/r/0/1/2/3/4/5/6/7/8/9'
+    return (fromFolder) => posix.relative(posix.join(root, inside), posix.join(root, fromFolder))
+  }
+  return null
+}
+
+/** A marker back to its path from the Function's folder, or null when it is not one `markerOf` can make. */
+function folderPathOf(markerOf: (fromFolder: string) => string, marker: string): string | null {
+  // Try the marker's own tail at each depth above the folder: `../shared/x.ts`, `../../lib/x.ts`, …
+  const parts = marker.split('/')
+  for (let up = 1; up <= 6; up++) {
+    for (let k = 0; k < parts.length; k++) {
+      const candidate = `${'../'.repeat(up)}${parts.slice(k).join('/')}`
+      if (markerOf(candidate) === marker) return candidate
+    }
+  }
+  for (let k = 0; k < parts.length; k++) {
+    const candidate = parts.slice(k).join('/')
+    if (markerOf(candidate) === marker) return candidate
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Merging what several Functions' bundles gave back for one file.
+
+/**
+ * One module from two bundles: every statement of the first, and each of the
+ * second's that declares a name the first lacks, in the second's order. Two
+ * Functions that use different parts of a shared file each brought only
+ * their part (the bundler drops what a Function does not use), so the file
+ * the project keeps is their union. Null when the two cannot be one file: a
+ * name both declare and import, or import from different places.
+ */
+export function mergeRecovered(a: RecoveredModule, b: RecoveredModule): RecoveredModule | null {
+  const statements = [...a.statements]
+  const declared = new Set(statements.flatMap((s) => s.declares))
+  const texts = new Set(statements.map((s) => s.text))
+  let pos = -1
+  for (const st of b.statements) {
+    const known = st.declares.length ? st.declares.every((n) => declared.has(n)) : texts.has(st.text)
+    if (known) {
+      const at = statements.findIndex((s) => s.text === st.text || (st.declares.length > 0 && s.declares.some((n) => st.declares.includes(n))))
+      if (at > pos) pos = at
+      continue
+    }
+    pos++
+    statements.splice(pos, 0, st)
+    st.declares.forEach((n) => declared.add(n))
+    texts.add(st.text)
+  }
+  const imports = new Map(a.imports)
+  for (const [local, imp] of b.imports) {
+    const has = imports.get(local)
+    if (has && (has.from !== imp.from || has.name !== imp.name)) return null
+    imports.set(local, imp)
+  }
+  if ([...imports.keys()].some((n) => declared.has(n))) return null
+  const exports = new Map(a.exports)
+  for (const [name, local] of b.exports) if (!exports.has(name)) exports.set(name, local)
+  const types = new Set([...a.types, ...b.types].filter((t) => !exports.has(t)))
+  return { path: a.path, from: [...new Set([...a.from, ...b.from])], statements, exports, types, imports }
+}
+
+// ---------------------------------------------------------------------------
+// Writing it.
+
+/** The first line of a file a pull recovered from a deployed bundle. */
+export const RECOVERED_HEADER = '// Recovered by `frontera local sync pull` from the deployed bundle of'
+
+function header(mod: RecoveredModule): string {
+  const froms = mod.from.length > 1 ? `${mod.from.slice(0, -1).join(', ')} and ${mod.from[mod.from.length - 1]}` : mod.from[0]
+  return [
+    `${RECOVERED_HEADER} ${froms}: its source in the workspace doesn’t hold this file.`,
+    `// This is bundled JavaScript, not the original: its types and any code ${mod.from.length > 1 ? 'those Functions' : 'the Function'} didn’t use are gone.`,
+    '// Replace it (and the .d.ts beside it) with the original source when you have it.',
+  ].join('\n')
+}
+
+const TYPE_PARAMS = '<_A = any, _B = any, _C = any, _D = any>'
+
+/** A class (or a capitalised value, as a class expression is) is a type too: `let e: Escalator`. */
+function usableAsType(mod: RecoveredModule, name: string, local: string): boolean {
+  return /^[A-Z]/.test(name) || mod.statements.some((s) => s.declares.includes(local) && /^class\s/.test(s.text))
+}
+
+/** The two files for a recovered module, by project path: `<path>.js` and `<path>.d.ts`. */
+export function recoveredFiles(mod: RecoveredModule): Record<string, string> {
+  const dir = posix.dirname(mod.path)
+  const spec = (to: string) => {
+    const rel = posix.relative(dir, to)
+    return rel.startsWith('.') ? rel : `./${rel}`
+  }
+  const bySource = new Map<string, string[]>()
+  for (const [local, imp] of [...mod.imports].sort(([a], [b]) => a.localeCompare(b))) {
+    const list = bySource.get(imp.from) ?? []
+    list.push(imp.name === local ? local : `${imp.name} as ${local}`)
+    bySource.set(imp.from, list)
+  }
+  const imports = [...bySource].map(([from, names]) => `import { ${names.join(', ')} } from '${spec(from)}'`)
+  const exported = [...mod.exports].sort(([a], [b]) => a.localeCompare(b))
+  const js = [
+    header(mod),
+    ...imports,
+    '',
+    ...mod.statements.map((s) => s.text),
+    '',
+    exported.length ? `export { ${exported.map(([name, local]) => (name === local ? name : `${local} as ${name}`)).join(', ')} };` : 'export {};',
+    '',
+  ].join('\n')
+  const dts = [
+    header(mod),
+    ...exported.flatMap(([name, local]) => (name === 'default'
+      ? ['declare const _default: any', 'export default _default']
+      : [`export declare const ${name}: any`, ...(usableAsType(mod, name, local) ? [`export type ${name}${TYPE_PARAMS} = any`] : [])])),
+    ...[...mod.types].filter((t) => t !== 'default' && !mod.exports.has(t)).sort().map((t) => `export type ${t}${TYPE_PARAMS} = any`),
+    ...(exported.length || mod.types.size ? [] : ['export {}']),
+    '',
+  ].join('\n')
+  return { [`${mod.path}.js`]: js, [`${mod.path}.d.ts`]: dts }
+}