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

package/src/directives.ts

@@ -0,0 +1,116 @@
+import type { DirectiveOptionType, Locale } from '@lincyaw/kernel'
+
+export interface DirectiveOptionInfo {
+  type?: DirectiveOptionType
+  doc?: Record<Locale, string>
+  values?: string[]
+}
+
+export interface DirectiveInfo {
+  name: string
+  doc: Record<Locale, string>
+  options: Record<string, DirectiveOptionInfo>
+}
+
+export const COMMON_DIRECTIVE_OPTIONS: Record<string, DirectiveOptionInfo> = {
+  reveal: {
+    doc: { 'zh-CN': '在下一步出现；`{slide}`、`{only}` 上写 `items` 时列表逐项出现。', 'en': 'Appears at the next step; `items` on `{slide}` and `{only}` reveals list items one per step.' },
+    values: ['items'],
+  },
+  label: { type: 'string', doc: { 'zh-CN': '块 ID。', 'en': 'Block id.' } },
+  audience: {
+    type: 'string',
+    doc: { 'zh-CN': '只给这些受众（逗号分隔），如 `teacher`；`presmium build --audience student` 不输出它。', 'en': 'Only for these audiences (comma-separated), e.g. `teacher`; `presmium build --audience student` leaves it out.' },
+    values: ['teacher', 'student'],
+  },
+}
+
+export const RUN_OPTION: DirectiveOptionInfo = {
+  type: 'string',
+  doc: { 'zh-CN': '`compile` 在构建时执行并录制输出，`live` 只在浏览器中执行，`both` 两者都做。', 'en': '`compile` records the output at build time, `live` runs in the browser, `both` does both.' },
+  values: ['compile', 'live', 'both'],
+}
+
+const STEP_RANGE: Record<string, DirectiveOptionInfo> = {
+  at: { type: 'number', doc: { 'zh-CN': '从指定步骤开始显示（从 0 开始），不能与 reveal 合用。', en: 'Shows from this zero-based step; cannot be combined with reveal.' } },
+  until: { type: 'number', doc: { 'zh-CN': '到指定步骤时隐藏；回退时恢复。', en: 'Hides at this step and returns when stepping back.' } },
+}
+
+const TITLE = { 'zh-CN': '标题。', 'en': 'Title.' }
+
+const CODE_OPTIONS: Record<string, DirectiveOptionInfo> = {
+  'caption': { type: 'string', doc: TITLE },
+  'filename': { type: 'string', doc: TITLE },
+  'emphasize-lines': { type: 'string', doc: { 'zh-CN': '每一步都强调的行，如 `2, 4-5`。', 'en': 'Lines highlighted at every step, e.g. `2, 4-5`.' } },
+  'run': RUN_OPTION,
+  'executor': { type: 'string', doc: { 'zh-CN': '执行器 ID。', 'en': 'Executor id.' } },
+  'timeout': { type: 'number', doc: { 'zh-CN': '毫秒。', 'en': 'Milliseconds.' } },
+  'env': { type: 'string', doc: { 'zh-CN': '运行环境：头部 `execute.environments` 中的名字，或 `browser`。', 'en': 'Where it runs: a name of `execute.environments` in the headmatter, or `browser`.' } },
+  'session': { type: 'string', doc: { 'zh-CN': '执行会话：同一会话的代码块共享解释器。', 'en': 'Execution session: code blocks of one session share the interpreter.' } },
+  'echo': { type: 'string', doc: { 'zh-CN': '`false`：只显示输出，Markdown 输出按正文显示。', 'en': '`false`: only the output shows, Markdown output as prose.' }, values: ['false'] },
+}
+
+const CLASS: DirectiveOptionInfo = { type: 'string', doc: { 'zh-CN': 'CSS 类名。', 'en': 'CSS class names.' } }
+
+const LAYOUT_DIRECTIVES: DirectiveInfo[] = [
+  {
+    name: 'grid',
+    doc: { 'zh-CN': '栅格：参数为四档屏宽（手机、小、中、大）的列数，如 `1 1 2 3`；正文为 `{card}` 或 `{grid-item}`。', 'en': 'A grid: the argument is the columns at four screen widths (phone, small, medium, large), e.g. `1 1 2 3`; the body holds `{card}` or `{grid-item}`.' },
+    options: { class: CLASS },
+  },
+  {
+    name: 'grid-item',
+    doc: { 'zh-CN': '栅格中的一格。', 'en': 'An item of a grid.' },
+    options: { columns: { type: 'number', doc: { 'zh-CN': '占一行 12 份中的几份。', 'en': 'How many twelfths of a row it takes.' } }, class: CLASS },
+  },
+  {
+    name: 'card',
+    doc: { 'zh-CN': '卡片：参数为标题；正文中 `^^^` 之前为页眉，`+++` 之后为页脚。', 'en': 'A card: the argument is its title; in the body, what precedes `^^^` is its header, what follows `+++` its footer.' },
+    options: {
+      link: { type: 'string', doc: { 'zh-CN': '整张卡片链接到的地址。', 'en': 'Where the whole card links to.' } },
+      header: { type: 'string', doc: { 'zh-CN': '页眉。', 'en': 'Header.' } },
+      footer: { type: 'string', doc: { 'zh-CN': '页脚。', 'en': 'Footer.' } },
+    },
+  },
+  {
+    name: 'tab-set',
+    doc: { 'zh-CN': '一组选项卡；正文为 `{tab-item}`。', 'en': 'A set of tabs; the body holds `{tab-item}`.' },
+    options: { class: CLASS },
+  },
+  {
+    name: 'tab-item',
+    doc: { 'zh-CN': '一个选项卡：参数为标题。', 'en': 'A tab: the argument is its title.' },
+    options: {
+      sync: { type: 'string', doc: { 'zh-CN': '同步键：选中它时，页面上同一键的选项卡一起切换。', 'en': 'Sync key: choosing it switches the tabs with the same key on the page.' } },
+      selected: { type: 'boolean', doc: { 'zh-CN': '开始时选中。', 'en': 'Selected at first.' } },
+    },
+  },
+]
+
+export const BUILTIN_DIRECTIVE_INFO: readonly DirectiveInfo[] = [
+  { name: 'slide', doc: { 'zh-CN': '上屏内容；正文为 MyST。', 'en': 'Content shown on screen; the body is MyST.' }, options: STEP_RANGE },
+  { name: 'only', doc: { 'zh-CN': '只在这些渲染端出现的内容，如 `{only} web, notebook`。', 'en': 'Content limited to renderers, e.g. `{only} web, notebook`.' }, options: STEP_RANGE },
+  { name: 'hints', doc: { 'zh-CN': '各渲染端的排版提示；正文为 YAML。', 'en': 'Layout hints per renderer; the body is YAML.' }, options: {} },
+  { name: 'config', doc: { 'zh-CN': '只在本章节生效的插件配置；正文为 YAML，键为插件 ID。', 'en': 'Plugin configuration of this section; the body is YAML keyed by plugin id.' }, options: {} },
+  { name: 'audience', doc: { 'zh-CN': '整个章节只给这些受众，如 `{audience} teacher`；放在章节顶层，没有正文。', 'en': 'The whole section is only for these audiences, e.g. `{audience} teacher`; at the top of a section, without a body.' }, options: {} },
+  {
+    name: 'component',
+    doc: { 'zh-CN': '插件组件，如 `{component} PmQuiz`；正文为 YAML 属性。', 'en': 'A plugin component, e.g. `{component} PmQuiz`; the body is YAML props.' },
+    options: { span: { type: 'number', doc: { 'zh-CN': '内部步数。', 'en': 'Internal steps.' } }, plugin: { type: 'string', doc: { 'zh-CN': '插件 ID。', 'en': 'Plugin id.' } } },
+  },
+  { name: 'include', doc: { 'zh-CN': '引入另一个源文件。', 'en': 'Includes another source file.' }, options: {} },
+  {
+    name: 'literalinclude',
+    doc: { 'zh-CN': '以代码显示一个文件（或其中几行）；参数为文件路径。', 'en': 'Shows a file (or some of its lines) as code; the argument is the file path.' },
+    options: {
+      'language': { type: 'string', doc: { 'zh-CN': '语言；默认按扩展名。', 'en': 'Language; by default from the extension.' } },
+      'lines': { type: 'string', doc: { 'zh-CN': '只显示这些行，如 `2, 4-6`。', 'en': 'Only these lines, e.g. `2, 4-6`.' } },
+      'start-after': { type: 'string', doc: { 'zh-CN': '从含这段文字的行之后开始。', 'en': 'Starts after the line with this text.' } },
+      'end-before': { type: 'string', doc: { 'zh-CN': '到含这段文字的行之前结束。', 'en': 'Ends before the line with this text.' } },
+      'caption': CODE_OPTIONS.caption!,
+      'emphasize-lines': CODE_OPTIONS['emphasize-lines']!,
+    },
+  },
+  ...['code', 'code-block', 'code-cell', 'sourcecode'].map(name => ({ name, doc: { 'zh-CN': '代码；参数为语言。', 'en': 'Code; the argument is the language.' }, options: CODE_OPTIONS })),
+  ...LAYOUT_DIRECTIVES,
+]

package/src/environments.ts

@@ -0,0 +1,148 @@
+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 readExecute(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: 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 executor = made.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
+      }
+      made.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,367 @@
+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'
+
+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 })
+  }
+
+  record(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 })
+  }
+
+  find(input: string): RecordedRun | undefined {
+    return this.recording(input)?.run
+  }
+
+  recording(input: string): { run: RecordedRun, environment?: string, revision: string } | undefined {
+    for (const record of this.#all().values()) {
+      if (record.input === input) return { run: this.#restore(record.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 {
+    if (!run.outputs) return run
+    return { ...run, outputs: run.outputs.map(output => mapData(output, (value) => {
+      if (!isRecord(value) || typeof value[BLOB_REF] !== 'string') return value
+      return this.#text(join(this.dir, BLOBS, value[BLOB_REF].replace(/[^0-9a-f]/g, '')))
+    })) }
+  }
+}
+
+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 ExecutionOptions {
+  env?: 'local' | 'serve'
+}
+
+export interface RunStats {
+  executed: number
+  cached: number
+  sandbox?: string
+}
+
+export interface ExecuteOptions extends ExecutionOptions {
+  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
+  }
+  return 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: ExecuteOptions): 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.recording(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()}`
+  for (const unit of pending) {
+    const executor = unit.executor!
+    const session = unit.session && `${compile}:${unit.session}`
+    const run = (request: RunRequest) => executor.run(session ? { ...request, session } : request, undefined, options.context)
+    try {
+      if (session) {
+        await executor.endSession?.(session)
+        sessions.push([executor, session])
+        const results = await Promise.all(unit.items.map(item => run(item.request)))
+        unit.items.forEach((item, i) => record(item, results[i]!, unit, cache, stats, say))
+      } else {
+        const item = unit.items[0]!
+        record(item, await run(item.request), unit, cache, stats, say)
+      }
+    } catch (error) {
+      for (const item of unit.items) fromRecording(item, cache, stats, say, executor.id, errorMessage(error))
+    }
+  }
+  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.record(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.find(item.input)
+  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/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
+    }
+  }
+}