@lincyaw/compiler 0.0.0-stage → 1.0.0-rc.1

package/src/environments.ts

@@ -0,0 +1,150 @@
+import { environmentExecutor, errorMessage, irBlocks, isRecord } from '@lincyaw/kernel'
+import type { CodeNode, EnvironmentContext, EnvironmentProvider, EnvironmentSpec, ExecuteConfig, Executor, Finding, IRDocument } from '@lincyaw/kernel'
+
+const PREFIX = environmentExecutor('')
+
+type At = (needle: string) => { file: string, line: number }
+
+export function toExecuteConfig(value: unknown, report: (finding: Finding) => void, at: At): ExecuteConfig {
+  if (value === undefined) return {}
+  const fail = (message: string, needle = 'execute') => report({ checkId: 'presmium.execute', severity: 'error', message, source: at(needle) })
+  if (!isRecord(value)) {
+    fail('`execute` must be a mapping, e.g. `execute: { environments: { box: { kind: devcontainer } } }`')
+    return {}
+  }
+  const execute: ExecuteConfig = {}
+  if (value.env !== undefined) {
+    if (typeof value.env === 'string' && value.env.trim()) execute.env = value.env.trim()
+    else fail('`execute.env` must be the name of an environment')
+  }
+  if (value.rerun === 'environment') execute.rerun = 'environment'
+  if (value.environments !== undefined) {
+    if (!isRecord(value.environments)) {
+      fail('`execute.environments` must map names to environments, e.g. `box: { kind: devcontainer }`')
+    } else {
+      const environments: Record<string, EnvironmentSpec> = {}
+      for (const [name, spec] of Object.entries(value.environments)) {
+        if (name === 'browser' || !/^[\w-]+$/.test(name)) fail(`environment "${name}": a name is letters, digits, \`_\` and \`-\`, and not \`browser\`, which is reserved`, `${name}:`)
+        else if (!isRecord(spec) || typeof spec.kind !== 'string' || !spec.kind) fail(`environment "${name}" needs a \`kind\`, e.g. jupyter, devcontainer, wasi, webgpu`, `${name}:`)
+        else environments[name] = spec as EnvironmentSpec
+      }
+      execute.environments = environments
+    }
+  }
+  if (execute.env && execute.env !== 'browser' && !execute.environments?.[execute.env]) fail(`\`execute.env\`: no environment "${execute.env}" in \`execute.environments\``)
+  return execute
+}
+
+export function environmentProviders(execute: ExecuteConfig, providers: Map<string, EnvironmentProvider>, report: (finding: Finding) => void, at: At): Map<string, EnvironmentProvider> {
+  const found = new Map<string, EnvironmentProvider>()
+  for (const [name, spec] of Object.entries(execute.environments ?? {})) {
+    const provider = providers.get(spec.kind)
+    if (provider) found.set(name, provider)
+    else report({ checkId: 'presmium.execute', severity: 'error', message: `environment "${name}": no plugin in \`plugins\` provides environments of kind ${spec.kind}`, source: at(`${name}:`) })
+  }
+  return found
+}
+
+export async function environmentExecutors(
+  execute: ExecuteConfig,
+  providers: Map<string, EnvironmentProvider>,
+  context: EnvironmentContext,
+  made: WeakMap<EnvironmentProvider, Map<string, Executor>>,
+  report: (finding: Finding) => void,
+  at: At,
+): Promise<Executor[]> {
+  const executors: Executor[] = []
+  for (const [name, provider] of providers) {
+    const spec = execute.environments![name]!
+    const key = JSON.stringify([name, spec])
+    let instances = made.get(provider)
+    if (!instances) made.set(provider, instances = new Map())
+    let executor = instances.get(key)
+    if (!executor) {
+      try {
+        executor = await provider.create(name, spec, context)
+      } catch (error) {
+        report({ checkId: 'presmium.execute', severity: 'error', message: `environment "${name}": the ${spec.kind} provider failed: ${errorMessage(error)}`, source: at(`${name}:`) })
+        continue
+      }
+      if (executor.id !== environmentExecutor(name)) {
+        report({ checkId: 'presmium.execute', severity: 'error', message: `environment "${name}": the ${spec.kind} provider made the executor ${executor.id}, not ${environmentExecutor(name)}`, source: at(`${name}:`) })
+        continue
+      }
+      instances.set(key, executor)
+    }
+    executors.push(executor)
+  }
+  return executors
+}
+
+export function checkRuns(doc: IRDocument, execute: ExecuteConfig, report: (finding: Finding) => void): void {
+  const sessions = new Map<string, string>()
+  for (const section of doc.sections) {
+    for (const block of irBlocks(section.blocks)) {
+      const run = block.node.type === 'code' ? block.node.run : undefined
+      if (!run) continue
+      const fail = (message: string) => report({ checkId: 'presmium.execute', severity: 'error', message, source: { file: block.source.file, line: block.source.line } })
+      const name = run.executor?.startsWith(PREFIX) ? run.executor.slice(PREFIX.length) : undefined
+      if (name !== undefined && !execute.environments?.[name]) fail(`:env: ${name}: no such environment in \`execute.environments\` of the headmatter`)
+      if (!run.session) continue
+      const where = run.executor ?? 'browser'
+      const first = sessions.get(run.session)
+      if (first === undefined) sessions.set(run.session, where)
+      else if (first !== where) fail(`session "${run.session}" runs in ${describe(first)} and here in ${describe(where)}; the blocks of a session share one environment`)
+    }
+  }
+}
+
+export function checkLanguages(doc: IRDocument, execute: ExecuteConfig, executors: readonly Executor[], report: (finding: Finding) => void): Set<CodeNode> {
+  const reported = new Set<CodeNode>()
+  for (const section of doc.sections) {
+    for (const block of irBlocks(section.blocks)) {
+      const run = block.node.type === 'code' ? block.node.run : undefined
+      const name = run?.executor?.startsWith(PREFIX) ? run.executor.slice(PREFIX.length) : undefined
+      const spec = name === undefined ? undefined : execute.environments?.[name]
+      const executor = spec?.languages?.length ? executors.find(e => e.id === run!.executor) : undefined
+      if (!run || !spec?.languages || !executor || executor.supports(run.lang)) continue
+      reported.add(block.node as CodeNode)
+      const runs = `runs ${spec.languages.join(', ')}, not ${run.lang}`
+      const fallback = execute.env === name ? ` (blocks that name none run in "${name}", the headmatter's execute.env)` : ''
+      report({
+        checkId: 'presmium.execute',
+        severity: 'error',
+        message: `environment "${name}" (${spec.kind}) ${runs}`,
+        hint: `name another environment with :env:${fallback}, or add ${run.lang} to the languages of "${name}"`,
+        source: { file: block.source.file, line: block.source.line },
+      })
+    }
+  }
+  return reported
+}
+
+function describe(executor: string): string {
+  return executor.startsWith(PREFIX) ? `environment ${executor.slice(PREFIX.length)}` : executor === 'browser' ? 'the default environment' : `executor ${executor}`
+}
+
+const CREDENTIALS = [
+  /^sk-[\w-]{16,}$/,
+  /^(?:gh[pousr]|github_pat)_\w{20,}$/,
+  /^xox[abposr]-[\w-]{10,}$/,
+  /^AKIA[0-9A-Z]{16}$/,
+  /^AIza[\w-]{30,}$/,
+  /^eyJ[\w-]{10,}\.[\w-]{10,}\.[\w-]{10,}$/,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+]
+const CREDENTIAL_KEY = /(?:^|[_-])(?:token|secret|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key)$/i
+
+export function checkSecrets(headmatter: Record<string, unknown>, report: (finding: Finding) => void, at: At): void {
+  const visit = (value: unknown, key: string, path: string) => {
+    if (typeof value === 'string') {
+      const looks = CREDENTIALS.some(pattern => pattern.test(value.trim())) || (CREDENTIAL_KEY.test(key) && value.trim().length >= 12 && !/\s/.test(value.trim()))
+      if (looks) report({ checkId: 'presmium.secrets', severity: 'warning', message: `${path} looks like a credential; credentials come from environment variables or a login (e.g. PRESMIUM_ENV_<NAME>_TOKEN), never from the deck, which is published`, source: at(`${key}:`) })
+    } else if (Array.isArray(value)) {
+      value.forEach((item, i) => visit(item, key, `${path}[${i}]`))
+    } else if (isRecord(value)) {
+      for (const [k, v] of Object.entries(value)) visit(v, k, path ? `${path}.${k}` : k)
+    }
+  }
+  visit(headmatter, '', '')
+}

package/src/execute.ts

@@ -0,0 +1,381 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { CREDENTIAL_VARIABLE, environmentExecutor, errorMessage, irBlocks, isRecord } from '@lincyaw/kernel'
+import type { CodeNode, Executor, Finding, IRBlock, IRDocument, RecordedRun, RunCache, RunContext, RunOutput, RunRequest, RunResult } from '@lincyaw/kernel'
+import { resourceEnvironment } from '@lincyaw/kernel/node'
+
+export const FREEZE_DIR = '.presmium/freeze'
+const BLOBS = 'blobs'
+const BLOB_LENGTH = 4096
+const BLOB_REF = 'presmium/blob'
+
+interface FreezeRecord {
+  input?: string
+  entry?: string
+  lang?: string
+  code?: string
+  environment?: string
+  revision?: string
+  run: RecordedRun
+}
+
+export class FreezeCache implements RunCache {
+  readonly dir: string
+  readonly entry: string
+  readonly used = new Set<string>()
+  #records?: Map<string, FreezeRecord>
+
+  constructor(dir: string, entry: string) {
+    this.dir = dir
+    this.entry = entry
+  }
+
+  get(key: string): RecordedRun | undefined {
+    const record = this.#read(`${key}.json`)
+    return record && this.#restore(record.run)
+  }
+
+  set(key: string, run: RecordedRun): void {
+    this.#write(key, { run })
+  }
+
+  /** Records a run under its cache key and drops the older recordings of the same input. */
+  recordRun(key: string, input: string, request: RunRequest, run: RecordedRun, environment: string, revision = ''): void {
+    for (const [file, record] of this.#all()) {
+      if (record.input !== input || file === `${key}.json`) continue
+      rmSync(join(this.dir, file), { force: true })
+      this.#records?.delete(file)
+    }
+    this.#write(key, { input, entry: this.entry, lang: request.lang, code: request.code, environment, ...revision ? { revision } : {}, run })
+  }
+
+  /** The recording of the input, made in whichever environment, whatever its cache key. */
+  findByInput(input: string): { run: RecordedRun, environment?: string, revision: string } | undefined {
+    for (const record of this.#all().values()) {
+      if (record.input !== input) continue
+      const run = this.#restore(record.run)
+      if (run) return { run, environment: record.environment, revision: record.revision ?? '' }
+    }
+    return undefined
+  }
+
+  prune(): number {
+    let removed = 0
+    for (const [file, record] of this.#all()) {
+      if (record.entry !== this.entry || !record.input || this.used.has(record.input)) continue
+      rmSync(join(this.dir, file), { force: true })
+      this.#records?.delete(file)
+      removed++
+    }
+    const referred = new Set<string>()
+    for (const record of this.#all().values()) blobRefs(record.run, referred)
+    let blobs: string[] = []
+    try {
+      blobs = readdirSync(join(this.dir, BLOBS))
+    } catch {}
+    for (const blob of blobs.filter(name => !referred.has(name))) rmSync(join(this.dir, BLOBS, blob), { force: true })
+    return removed
+  }
+
+  #all(): Map<string, FreezeRecord> {
+    if (!this.#records) {
+      this.#records = new Map()
+      let files: string[] = []
+      try {
+        files = readdirSync(this.dir).filter(f => f.endsWith('.json')).sort()
+      } catch {
+      }
+      for (const file of files) {
+        const record = this.#read(file)
+        if (record) this.#records.set(file, record)
+      }
+    }
+    return this.#records
+  }
+
+  #text(file: string): string | undefined {
+    try {
+      return readFileSync(file, 'utf8')
+    } catch {
+      return undefined
+    }
+  }
+
+  #read(file: string): FreezeRecord | undefined {
+    const text = this.#text(join(this.dir, file))
+    if (text === undefined) return undefined
+    try {
+      const data: unknown = JSON.parse(text)
+      return isRecord(data) && isRecord(data.run) ? data as unknown as FreezeRecord : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  #write(key: string, record: FreezeRecord): void {
+    mkdirSync(this.dir, { recursive: true })
+    const stored = { ...record, run: this.#store(record.run) }
+    writeFileSync(join(this.dir, `${key}.json`), `${JSON.stringify(stored, null, 2)}\n`)
+    this.#records?.set(`${key}.json`, stored)
+  }
+
+  #store(run: RecordedRun): RecordedRun {
+    if (!run.outputs) return run
+    return { ...run, outputs: run.outputs.map(output => mapData(output, (value) => {
+      const text = Array.isArray(value) && value.every(v => typeof v === 'string') ? value.join('') : value
+      if (typeof text !== 'string' || text.length <= BLOB_LENGTH) return value
+      const name = createHash('sha256').update(text).digest('hex')
+      const file = join(this.dir, BLOBS, name)
+      if (!existsSync(file)) {
+        mkdirSync(join(this.dir, BLOBS), { recursive: true })
+        writeFileSync(file, text)
+      }
+      return { [BLOB_REF]: name }
+    })) }
+  }
+
+  #restore(run: RecordedRun): RecordedRun | undefined {
+    if (!run.outputs) return run
+    let complete = true
+    const outputs = run.outputs.map(output => mapData(output, (value) => {
+      if (!isRecord(value) || typeof value[BLOB_REF] !== 'string') return value
+      const text = this.#text(join(this.dir, BLOBS, value[BLOB_REF].replace(/[^0-9a-f]/g, '')))
+      if (text === undefined) complete = false
+      return text
+    }))
+    return complete ? { ...run, outputs } : undefined
+  }
+}
+
+function mapData(output: RunOutput, map: (value: unknown) => unknown): RunOutput {
+  if (output.output_type !== 'display_data' && output.output_type !== 'execute_result') return output
+  const data: Record<string, unknown> = {}
+  for (const [mime, value] of Object.entries(output.data)) {
+    const mapped = map(value)
+    if (mapped !== undefined) data[mime] = mapped
+  }
+  return { ...output, data }
+}
+
+function blobRefs(run: RecordedRun, into: Set<string>): void {
+  for (const output of run.outputs ?? []) {
+    mapData(output, (value) => {
+      if (isRecord(value) && typeof value[BLOB_REF] === 'string') into.add(value[BLOB_REF])
+      return value
+    })
+  }
+}
+
+export interface RunEnvironmentOptions {
+  env?: 'local' | 'serve'
+}
+
+export interface RunStats {
+  executed: number
+  cached: number
+  sandbox?: string
+}
+
+export interface ExecutePassOptions extends RunEnvironmentOptions {
+  signal?: AbortSignal
+  rerun?: boolean
+  context: RunContext
+  unsupported?: ReadonlySet<CodeNode>
+}
+
+const SERVE_ALLOWED = /^(?:PATH|LANG|LC_\w+|TZ|TMPDIR)$/
+
+export function runEnvironment(rules: 'local' | 'serve', passEnv: readonly string[], workspaceRoot: string, source: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [name, value] of Object.entries(source)) {
+    if (value === undefined) continue
+    const kept = rules === 'serve' ? SERVE_ALLOWED.test(name) : !/^PRESMIUM_/i.test(name) && !CREDENTIAL_VARIABLE.test(name)
+    if (kept) env[name] = value
+  }
+  if (rules === 'serve') {
+    env.HOME = runHome(workspaceRoot, source)
+    env.PYTHONNOUSERSITE = '1'
+  }
+  for (const name of passEnv) {
+    const value = source[name]
+    if (value !== undefined) env[name] = value
+  }
+  if (source.PRESMIUM_MAX_THREADS !== undefined) env.PRESMIUM_MAX_THREADS = source.PRESMIUM_MAX_THREADS
+  return resourceEnvironment(env)
+}
+
+function runHome(workspaceRoot: string, source: NodeJS.ProcessEnv): string {
+  const state = source.XDG_STATE_HOME || join(homedir(), '.local', 'state')
+  const home = join(state, 'presmium', 'run-home', createHash('sha256').update(workspaceRoot).digest('hex').slice(0, 16))
+  mkdirSync(home, { recursive: true, mode: 0o700 })
+  const stat = lstatSync(home)
+  const uid = process.getuid?.()
+  if (!stat.isDirectory() || (uid !== undefined && stat.uid !== uid) || (stat.mode & 0o077) !== 0) {
+    throw new Error(`the run HOME ${home} is not a private directory of this user`)
+  }
+  return home
+}
+
+interface Item {
+  node: CodeNode
+  block: IRBlock
+  request: RunRequest
+  input: string
+  key?: string
+}
+
+interface Unit {
+  session?: string
+  items: Item[]
+  executor?: Executor
+  environment: string
+  revision?: string
+}
+
+type Report = (severity: Finding['severity'], message: string, block: IRBlock) => void
+
+export async function executePass(doc: IRDocument, executors: Executor[], cache: FreezeCache, report: (finding: Finding) => void, options: ExecutePassOptions): Promise<RunStats> {
+  const stats: RunStats = { executed: 0, cached: 0, ...options.context.sandbox ? { sandbox: options.context.sandbox.kind } : {} }
+  const say: Report = (severity, message, block) =>
+    report({ checkId: 'presmium.execute', severity, message, source: { file: block.source.file, line: block.source.line } })
+  const units = collect(doc, cache)
+
+  const pending: Unit[] = []
+  for (const unit of units) {
+    const run = unit.items[0]!.node.run!
+    unit.executor = run.executor
+      ? executors.find(e => e.id === run.executor && e.supports(run.lang))
+      : executors.find(e => !e.id.startsWith(environmentExecutor('')) && e.supports(run.lang))
+    if (!unit.executor) {
+      for (const item of unit.items) fromRecording(item, cache, stats, say, run.executor, undefined, options.unsupported?.has(item.node))
+      continue
+    }
+    try {
+      unit.environment = await unit.executor.fingerprint?.(run.lang) ?? ''
+      unit.revision = await unit.executor.revision?.(run.lang) ?? ''
+    } catch (error) {
+      for (const item of unit.items) fromRecording(item, cache, stats, say, run.executor, errorMessage(error))
+      continue
+    }
+    let previous = unit.session
+    for (const item of unit.items) {
+      const made = { executor: unit.executor.id, environment: unit.environment, ...unit.revision ? { revision: unit.revision } : {} }
+      item.key = hash(unit.session ? { previous, input: item.input, ...made } : { input: item.input, ...made })
+      previous = item.key
+    }
+    const cached = unit.items.map(item => cache.get(item.key!))
+    if (cached.every(Boolean)) {
+      unit.items.forEach((item, i) => item.node.outputs = [cached[i]!])
+      stats.cached += unit.items.length
+      continue
+    }
+    const others = options.rerun ? [] : unit.items.map(item => cache.findByInput(item.input)).map(other => (other?.revision === unit.revision ? other : undefined))
+    if (others.length > 0 && others.every(Boolean)) {
+      unit.items.forEach((item, i) => {
+        const other = others[i]!
+        item.node.outputs = [other.run]
+        const made = other.environment === undefined ? 'another environment' : `"${other.environment || 'no fingerprint'}"`
+        say('warning', `block ${item.block.id}: its recorded output was made with ${made}, this build has "${unit.environment || 'no fingerprint'}"; the recording is reused (\`execute: { rerun: environment }\` in the headmatter runs it again)`, item.block)
+      })
+      stats.cached += unit.items.length
+      continue
+    }
+    pending.push(unit)
+  }
+
+  const sessions: [Executor, string][] = []
+  const compile = `compile:${randomUUID()}`
+  try {
+    for (const unit of pending) {
+      options.signal?.throwIfAborted()
+      const executor = unit.executor!
+      const session = unit.session && `${compile}:${unit.session}`
+      const run = (request: RunRequest) => executor.run(session ? { ...request, session } : request, options.signal, options.context)
+      try {
+        if (session) {
+          await executor.endSession?.(session)
+          sessions.push([executor, session])
+          // Submit a logical session together: executors batch these into one runtime.
+          const results = await Promise.all(unit.items.map(item => run(item.request)))
+          options.signal?.throwIfAborted()
+          unit.items.forEach((item, i) => record(item, results[i]!, unit, cache, stats, say))
+        } else {
+          const item = unit.items[0]!
+          const result = await run(item.request)
+          options.signal?.throwIfAborted()
+          record(item, result, unit, cache, stats, say)
+        }
+      } catch (error) {
+        options.signal?.throwIfAborted()
+        for (const item of unit.items) fromRecording(item, cache, stats, say, executor.id, errorMessage(error))
+      }
+    }
+  } finally {
+    for (const [executor, session] of sessions) await executor.endSession?.(session)?.catch(() => {})
+  }
+  return stats
+}
+
+function collect(doc: IRDocument, cache: FreezeCache): Unit[] {
+  const units: Unit[] = []
+  const sessions = new Map<string, Unit>()
+  for (const section of doc.sections) {
+    for (const block of irBlocks(section.blocks)) {
+      const node = block.node
+      if (node.type !== 'code' || !node.run || node.run.when === 'live') continue
+      const run = node.run
+      const request: RunRequest = { lang: run.lang, code: node.value }
+      if (run.args) request.args = run.args
+      if (run.stdin !== undefined) request.stdin = run.stdin
+      if (run.timeoutMs !== undefined) request.timeoutMs = run.timeoutMs
+      const fields = { lang: request.lang, code: request.code, args: request.args, stdin: request.stdin, executor: run.executor }
+      if (!run.session) {
+        const input = hash(fields)
+        cache.used.add(input)
+        units.push({ items: [{ node, block, request, input }], environment: '' })
+        continue
+      }
+      const session = `${cache.entry}:${run.session}`
+      request.session = session
+      let unit = sessions.get(session)
+      if (!unit) {
+        unit = { session, items: [], environment: '' }
+        sessions.set(session, unit)
+        units.push(unit)
+      }
+      const input = hash({ previous: unit.items.at(-1)?.input ?? session, ...fields })
+      cache.used.add(input)
+      unit.items.push({ node, block, request, input })
+    }
+  }
+  return units
+}
+
+function record(item: Item, result: RunResult, unit: Unit, cache: FreezeCache, stats: RunStats, say: Report): void {
+  const recorded: RecordedRun = { ...result, cacheKey: item.key! }
+  item.node.outputs = [recorded]
+  stats.executed++
+  if (!result.timedOut) cache.recordRun(item.key!, item.input, item.request, recorded, unit.environment, unit.revision)
+  if (!result.ok) say('warning', `block ${item.block.id} exited with ${result.timedOut ? 'a timeout' : result.exitCode === null ? `no exit code: ${result.stderr.trim().split('\n')[0]}` : `code ${result.exitCode}`}`, item.block)
+}
+
+function fromRecording(item: Item, cache: FreezeCache, stats: RunStats, say: Report, executor: string | undefined, failure?: string, reported = false): void {
+  const recorded = cache.findByInput(item.input)?.run
+  const which = executor ?? item.request.lang
+  if (recorded) {
+    item.node.outputs = [recorded]
+    stats.cached++
+    if (failure) say('warning', `executor ${which} is unavailable (${failure}); block ${item.block.id} shows its recorded output`, item.block)
+    return
+  }
+  if (reported) return
+  if (failure) return say('error', `executor ${which} failed on block ${item.block.id}: ${failure}`, item.block)
+  const environment = executor?.startsWith(environmentExecutor(''))
+  say(environment ? 'error' : 'warning', `no executor for ${which} and no recorded output in ${FREEZE_DIR}; block ${item.block.id} has no output`, item.block)
+}
+
+function hash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}

package/src/export.ts

@@ -0,0 +1,49 @@
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { ExportOutput } from '@lincyaw/kernel'
+import { build } from './build.ts'
+import type { Compilation } from './compiler.ts'
+import { documentExporters } from './renderers.ts'
+
+// Below the export's directory: the builds its exporter asks for, removed once it is done.
+const BUILDS = '.build'
+
+export interface ExportOptions {
+  /** An empty directory for the files. */
+  outDir: string
+  /** What the one who asked chose (`ExportContext.options`). */
+  options?: Record<string, unknown>
+  signal?: AbortSignal
+  progress?(phase: string, done?: number, total?: number): void
+  log?(line: string): void
+}
+
+/** Makes the document's export `id` (a plugin's exporter: the slides as a PDF, the lecture as a video) into `outDir`. */
+export async function exportDocument(compilation: Compilation, id: string, options: ExportOptions): Promise<ExportOutput> {
+  const found = (await documentExporters(compilation)).find(({ exporter }) => exporter.id === id)
+  if (!found) throw new Error(`no plugin of the document exports ${id}`)
+  const builds = join(options.outDir, BUILDS)
+  try {
+    return await found.exporter.run({
+      deckDir: compilation.deckDir,
+      workspaceRoot: compilation.workspaceRoot,
+      source: compilation.doc.source,
+      config: found.config,
+      outDir: options.outDir,
+      signal: options.signal ?? new AbortController().signal,
+      progress: options.progress ?? (() => {}),
+      log: options.log ?? (() => {}),
+      options: options.options ?? {},
+      async build(renderer, config = {}) {
+        const { renderers } = compilation.doc.config
+        const configured = { ...compilation, doc: { ...compilation.doc, config: { ...compilation.doc.config, renderers: { ...renderers, [renderer]: { ...renderers[renderer], ...config } } } } }
+        const report = await build(configured, { outDir: join(builds, renderer), to: [renderer], base: '/', ...options.log ? { log: options.log } : {} })
+        const own = report.outputs.find(output => output.renderer === renderer)
+        if (!own) throw new Error(report.findings.filter(f => f.severity === 'error').map(f => f.message).join('; ') || `the ${renderer} renderer made nothing`)
+        return own.outDir
+      },
+    })
+  } finally {
+    await rm(builds, { recursive: true, force: true })
+  }
+}

package/src/footnotes.ts

@@ -0,0 +1,39 @@
+import { docBlocks, nodeMdast } from '@lincyaw/kernel'
+import type { IRDocument, MdastNode } from '@lincyaw/kernel'
+import { unique } from './sections.ts'
+
+const FOOTNOTE = new Set(['footnoteReference', 'footnoteDefinition'])
+
+export function numberFootnotes(doc: IRDocument, files: readonly string[]): void {
+  const byFile = new Map<string, MdastNode[]>(files.map(file => [file, []]))
+  const collect = (node: MdastNode, into: MdastNode[]) => {
+    if (FOOTNOTE.has(node.type) && typeof node.identifier === 'string') into.push(node)
+    node.children?.forEach(child => collect(child, into))
+  }
+  for (const { block } of docBlocks(doc)) {
+    const into = byFile.get(block.source.file) ?? byFile.set(block.source.file, []).get(block.source.file)!
+    for (const tree of nodeMdast(block.node)) collect(tree, into)
+  }
+
+  const used = new Set<string>()
+  for (const nodes of byFile.values()) {
+    const rename = new Map<string, string>()
+    for (const node of nodes) {
+      const id = node.identifier as string
+      if (node.type !== 'footnoteDefinition' || rename.has(id)) continue
+      rename.set(id, unique(id, used))
+    }
+    const numbers = new Map<string, number>()
+    for (const type of ['footnoteReference', 'footnoteDefinition']) {
+      for (const node of nodes) {
+        const id = node.identifier as string
+        if (node.type === type && !numbers.has(id)) numbers.set(id, numbers.size + 1)
+      }
+    }
+    for (const node of nodes) {
+      const id = node.identifier as string
+      node.enumerator = String(numbers.get(id))
+      node.identifier = rename.get(id) ?? id
+    }
+  }
+}