@starpak/lang 0.0.0-stage → 0.1.3

package/src/emit/ts.ts

@@ -0,0 +1,1024 @@
+/**
+ * Spak Lang - TypeScript emitter
+ *
+ * Lowers a checked Spak `Program` into standalone ESM TypeScript that can be
+ * executed directly with `node --import tsx <file>`.
+ *
+ * Design notes:
+ * - Types are erased from runtime positions; `type` aliases are kept.
+ * - The output embeds a tiny runtime shim (`// spak runtime`) so generated
+ *   files do not depend on any external package.
+ * - Spak's Lua-flavoured method calls (`list:sort`, `s:split`, ...) lower to
+ *   calls on that shim; unknown methods keep normal JS method syntax.
+ * - Slices are 1-based and inclusive: `list[1..n]` -> `list.slice(0, n)`.
+ * - `fs` named imports stay async when the binding is awaited, so
+ *   `import { readFile } from "fs"` + `await readFile(...)` works. Imports that
+ *   are never awaited keep the historical synchronous binding (hello.spk
+ *   compatibility); `import { readFileSync }` is always explicit.
+ */
+
+import type {
+  Assign,
+  Block,
+  Call,
+  ClassDecl,
+  Decorator,
+  Expr,
+  ExportDecl,
+  FnDecl,
+  ForIn,
+  ForNumeric,
+  FunctionExpr,
+  Ident,
+  ImportDecl,
+  ImportForm,
+  Index,
+  MatchStmt,
+  Param,
+  Pattern,
+  Program,
+  Statement,
+  StringLit,
+  Table,
+  TablePattern,
+  TryStmt,
+  TypeAliasDecl,
+  TypeAnn,
+  VarDecl,
+} from '../ast'
+import { versionBanner } from '../version'
+
+export interface EmitOptions {
+  /** Emit the inlined runtime shim. Defaults to true. */
+  runtime?: boolean
+  /** Header comment; set to an empty string to omit it. */
+  banner?: string
+  /** Indentation unit. Defaults to two spaces. */
+  indent?: string
+  /**
+   * Optional artifact name. When `version` is set (and `banner` is not), the
+   * banner becomes `// spak:<name>:<version>`, matching spm's build banners.
+   */
+  name?: string
+  /**
+   * Artifact version, 3 or 4 numeric segments (`1.0.0` / `1.0.0.0`). Parsed by
+   * the same rules as spm's `parseVersion`; invalid values throw.
+   */
+  version?: string
+}
+
+/** Lua-style methods that are backed by the runtime shim. */
+const RUNTIME_METHODS = new Set(['push', 'pop', 'sort', 'split', 'len'])
+
+/** Node builtins whose Spak `fs` surface uses the sync/async compat shim. */
+const FS_SOURCES = new Set(['fs', 'node:fs'])
+/** Node `fs` functions that also exist as `*Sync` and `fs/promises` variants. */
+const FS_SYNC = new Set([
+  'access', 'appendFile', 'chmod', 'chown', 'close', 'copyFile', 'cp',
+  'exists', 'fchmod', 'fchown', 'fstat', 'fsync', 'ftruncate', 'futimes',
+  'glob', 'lchmod', 'lchown', 'link', 'lstat', 'lutimes', 'mkdir', 'mkdtemp',
+  'open', 'opendir', 'read', 'readFile', 'readdir', 'readlink', 'readv',
+  'realpath', 'rename', 'rm', 'rmdir', 'stat', 'statfs', 'symlink',
+  'truncate', 'unlink', 'utimes', 'write', 'writeFile', 'writev',
+])
+
+const RUNTIME = `// spak runtime (inlined helpers, no external dependencies)
+const __spak = {
+  len(x) {
+    if (x === null || x === undefined) return 0
+    if (typeof x === "string" || Array.isArray(x)) return x.length
+    if (x instanceof Map || x instanceof Set) return x.size
+    if (typeof x === "object") return Object.keys(x).length
+    return 0
+  },
+  range(from, to, inclusive = true) {
+    const out = []
+    const step = from <= to ? 1 : -1
+    const end = inclusive ? to : to - step
+    for (let i = from; step > 0 ? i <= end : i >= end; i += step) out.push(i)
+    return out
+  },
+  slice(x, from, to, inclusive = true) {
+    // 1-based, end-inclusive bounds. Empty ranges (1..0, 3..2) must be empty,
+    // so clamp instead of letting a negative end mean "from the tail".
+    const length = typeof x === "string" || Array.isArray(x) ? x.length : 0
+    const rawStart = Number(from) - 1
+    const rawEnd = inclusive ? Number(to) : Number(to) - 1
+    const start = Math.max(0, Number.isFinite(rawStart) ? rawStart : 0)
+    const end = Number.isFinite(rawEnd) ? rawEnd : -1
+    if (end < start || start >= length) return x.slice(0, 0)
+    return x.slice(start, Math.min(end, length))
+  },
+  idx(x, i) {
+    // Lua-style 1-based indexing for sequences; plain maps keep their keys.
+    if (Array.isArray(x) || typeof x === "string") return x[Number(i) - 1]
+    return x[i]
+  },
+  split(s, sep) {
+    return String(s).split(sep)
+  },
+  push(t, v) {
+    if (Array.isArray(t)) t.push(v)
+    else if (typeof t.length === "number") t[t.length] = v
+    else t[Object.keys(t).length] = v
+    return t
+  },
+  pop(t) {
+    if (Array.isArray(t)) return t.pop()
+    const keys = Object.keys(t)
+    if (!keys.length) return null
+    const key = keys[keys.length - 1]
+    const value = t[key]
+    delete t[key]
+    return value
+  },
+  sort(t, cmp) {
+    if (!cmp) {
+      t.sort()
+      return t
+    }
+    t.sort((a, b) => {
+      const result = cmp(a, b)
+      if (typeof result === "number") return result
+      if (result) return -1
+      return cmp(b, a) ? 1 : 0
+    })
+    return t
+  },
+  entries(t) {
+    if (t instanceof Map) return Array.from(t.entries())
+    if (t instanceof Set) return Array.from(t.entries())
+    if (Array.isArray(t) || typeof t === "string") return Array.from(t.entries())
+    return Object.entries(t)
+  },
+  iter(t) {
+    if (t === null || t === undefined) return []
+    if (typeof t === "string" || Array.isArray(t)) return t
+    if (t instanceof Map || t instanceof Set) return t
+    if (typeof t[Symbol.iterator] === "function") return t
+    return Object.keys(t)
+  }
+}
+function len(x) { return __spak.len(x) }
+function range(from, to) { return __spak.range(from, to, true) }
+function print(...args) { console.log(...args) }
+function tostring(x) { return String(x) }
+`
+
+class Emitter {
+  private lines: string[] = []
+  private level = 0
+  private scopes: Array<Set<string>> = [new Set()]
+  private temp = 0
+  /** Identifiers used directly under `await`; drives the async `fs` surface. */
+  private awaited = new Set<string>()
+  private readonly options: EmitOptions
+
+  constructor(options: EmitOptions = {}) {
+    this.options = options
+  }
+
+  private get unit(): string {
+    return this.options.indent ?? '  '
+  }
+
+  private pad(extra = 0): string {
+    return this.unit.repeat(Math.max(0, this.level + extra))
+  }
+
+  private line(text = ''): void {
+    this.lines.push(text ? this.pad() + text : '')
+  }
+
+  private withScope(fn: () => void): void {
+    this.scopes.push(new Set())
+    this.level++
+    try {
+      fn()
+    } finally {
+      this.level--
+      this.scopes.pop()
+    }
+  }
+
+  private declare(name: string): void {
+    this.scopes[this.scopes.length - 1].add(name)
+  }
+
+  private declared(name: string): boolean {
+    return this.scopes.some(scope => scope.has(name))
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Program                                                           */
+  /* ---------------------------------------------------------------- */
+
+  emitProgram(program: Program): string {
+    this.awaited = collectAwaitedIdentifiers(program)
+    for (const statement of program.body) this.emitStatement(statement)
+    const chunks: string[] = []
+    const defaultBanner = this.options.version
+      ? versionBanner(this.options.name ?? 'spak', this.options.version)
+      : '// Generated by Spak emitTypeScript'
+    const banner = this.options.banner ?? defaultBanner
+    if (banner) chunks.push(banner)
+    if (this.options.runtime !== false) chunks.push(RUNTIME.replace(/\n$/, ''))
+    chunks.push(this.lines.join('\n'))
+    return chunks.filter(Boolean).join('\n\n') + '\n'
+  }
+
+  private emitStatement(statement: Statement, exported = false): void {
+    switch (statement.kind) {
+      case 'VarDecl':
+        this.emitVarDecl(statement, exported)
+        return
+      case 'Assign':
+        this.emitAssign(statement)
+        return
+      case 'FnDecl':
+        this.emitFnDecl(statement, exported)
+        return
+      case 'ClassDecl':
+        this.emitClassDecl(statement, exported)
+        return
+      case 'IfStmt':
+        this.emitIf(statement)
+        return
+      case 'UnlessStmt':
+        this.line(`if (!(${this.expr(statement.cond)})) {`)
+        this.withScope(() => this.emitBlock(statement.body))
+        this.line('}')
+        return
+      case 'WhileStmt':
+        this.line(`while (${this.expr(statement.cond)}) {`)
+        this.withScope(() => this.emitBlock(statement.body))
+        this.line('}')
+        return
+      case 'RepeatStmt':
+        this.line('do {')
+        this.withScope(() => this.emitBlock(statement.body))
+        this.line(`} while (!(${this.expr(statement.cond)}));`)
+        return
+      case 'ForNumeric':
+        this.emitForNumeric(statement)
+        return
+      case 'ForIn':
+        this.emitForIn(statement)
+        return
+      case 'ReturnStmt': {
+        if (statement.values.length === 0) this.line('return;')
+        else if (statement.values.length === 1) this.line(`return ${this.expr(statement.values[0])};`)
+        else this.line(`return [${statement.values.map(value => this.expr(value)).join(', ')}];`)
+        return
+      }
+      case 'BreakStmt':
+        this.line('break;')
+        return
+      case 'ContinueStmt':
+        this.line('continue;')
+        return
+      case 'MatchStmt':
+        this.emitMatch(statement)
+        return
+      case 'TryStmt':
+        this.emitTry(statement)
+        return
+      case 'ImportDecl':
+        this.emitImport(statement)
+        return
+      case 'ExportDecl':
+        this.emitStatement((statement as ExportDecl).declaration, true)
+        return
+      case 'ExportDefault':
+        this.line(`export default ${this.expr(statement.expr)};`)
+        return
+      case 'TypeAliasDecl':
+        this.emitTypeAlias(statement, exported)
+        return
+      case 'ThrowStmt':
+        this.line(`throw ${this.expr(statement.value)};`)
+        return
+      case 'SpawnStmt': {
+        const value = this.expr(statement.value)
+        if (statement.value.kind === 'FunctionExpr') this.line(`void Promise.resolve((${value})());`)
+        else this.line(`void Promise.resolve(${value});`)
+        return
+      }
+      case 'ExprStmt':
+        this.line(`${this.expr(statement.expr)};`)
+        return
+      default:
+        this.line(`// unsupported statement: ${(statement as Statement).kind}`)
+    }
+  }
+
+  private emitBlock(block: Block | undefined): void {
+    if (!block) return
+    for (const statement of block.body) this.emitStatement(statement)
+  }
+
+  /** Comments only: used for positions that cannot be wrapped at runtime. */
+  private emitDecorators(decorators: Decorator[] | undefined): void {
+    if (!decorators?.length) return
+    for (const decorator of decorators) {
+      this.line(`// @${decorator.name}${this.decoratorArgs(decorator)}`)
+    }
+  }
+
+  private decoratorArgs(decorator: Decorator): string {
+    const args = decorator.args.map(arg => this.expr(arg)).join(', ')
+    return args ? `(${args})` : ''
+  }
+
+  /** Decorator as a callable expression: `memo`, `route("GET", "/x")`. */
+  private decoratorCall(decorator: Decorator): string {
+    return decorator.args.length
+      ? `${decorator.name}(${decorator.args.map(arg => this.expr(arg)).join(', ')})`
+      : decorator.name
+  }
+
+  /**
+   * Emits executable decorator wrappers (`target = dec(target)`), innermost
+   * decorator first, matching the docs' `@decorator fn` => `f = decorator(f)`.
+   */
+  private applyDecorators(target: string, decorators: Decorator[] | undefined): void {
+    if (!decorators?.length) return
+    for (const decorator of [...decorators].reverse()) {
+      this.line(`${target} = ${this.decoratorCall(decorator)}(${target});`)
+    }
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Declarations                                                      */
+  /* ---------------------------------------------------------------- */
+
+  private emitVarDecl(node: VarDecl, exported: boolean): void {
+    if (node.doc) this.emitDoc(node.doc)
+    this.emitDecorators(node.decorators)
+
+    const pairs = node.names.map((entry, index) => {
+      const value = node.values[index]
+      return { name: entry.name, value: value ? this.expr(value) : undefined }
+    })
+
+    if (node.scope === 'global') {
+      for (const pair of pairs) {
+        const value = pair.value ?? 'undefined'
+        this.line(`globalThis.${pair.name} = ${value};`)
+        if (exported) this.line(`export const ${pair.name} = globalThis.${pair.name};`)
+      }
+      return
+    }
+
+    const declaredHere = pairs.some(pair => this.declared(pair.name))
+    if (!declaredHere) {
+      const keyword = node.scope === 'const' ? 'const' : 'let'
+      const prefix = exported ? 'export ' : ''
+      const assign = pairs.map(pair => pair.value === undefined ? pair.name : `${pair.name} = ${pair.value}`)
+      this.line(`${prefix}${keyword} ${assign.join(', ')};`)
+      for (const pair of pairs) this.declare(pair.name)
+      return
+    }
+
+    for (const pair of pairs) {
+      if (!this.declared(pair.name)) {
+        const keyword = node.scope === 'const' ? 'const' : 'let'
+        this.declare(pair.name)
+        this.line(pair.value === undefined ? `${keyword} ${pair.name};` : `${keyword} ${pair.name} = ${pair.value};`)
+      } else if (pair.value !== undefined) {
+        this.line(`${pair.name} = ${pair.value};`)
+      }
+    }
+  }
+
+  private emitDoc(doc: string): void {
+    const lines = doc.split(/\r?\n/)
+    if (lines.length === 1) {
+      this.line(`/** ${lines[0]} */`)
+      return
+    }
+    this.line('/**')
+    for (const text of lines) this.line(` * ${text}`)
+    this.line(' */')
+  }
+
+  private emitAssign(node: Assign): void {
+    const values = node.values
+    node.targets.forEach((target, index) => {
+      const value = values[index] ? this.expr(values[index]) : 'undefined'
+      if (this.isPattern(target)) {
+        this.emitPatternAssign(target, value)
+        return
+      }
+      this.line(`${this.expr(target)} = ${value};`)
+    })
+  }
+
+  private isPattern(target: Expr | Pattern): target is Pattern {
+    return target.kind === 'TablePattern' || target.kind === 'ArrayPattern'
+  }
+
+  private emitPatternAssign(pattern: Pattern, value: string): void {
+    if (pattern.kind === 'ArrayPattern') {
+      const names = pattern.elements
+      this.line(`let [${names.join(', ')}] = ${value};`)
+      for (const name of names) this.declare(name)
+      return
+    }
+    const table = pattern as TablePattern
+    const entries = table.entries.map((entry) => {
+      const target = entry.target ?? entry.key
+      if (entry.default) return `${entry.key}: ${target} = ${this.expr(entry.default)}`
+      return entry.target ? `${entry.key}: ${target}` : entry.key
+    })
+    this.line(`let { ${entries.join(', ')} } = ${value};`)
+    for (const entry of table.entries) this.declare(entry.target ?? entry.key)
+  }
+
+  private emitFnDecl(node: FnDecl, exported: boolean): void {
+    if (node.doc) this.emitDoc(node.doc)
+    this.emitDecorators(node.decorators)
+
+    if (node.receiver) {
+      const fn = this.renderFunction(node)
+      const target = `${node.receiver}.${propertyName(node.name)}`
+      this.line(`${target} = ${fn};`)
+      this.applyDecorators(target, node.decorators)
+      return
+    }
+
+    this.declare(node.name)
+    const prefix = exported ? 'export ' : ''
+    this.line(`${prefix}${node.async ? 'async ' : ''}function ${node.name}(${this.emitParams(node.params)}) {`)
+    this.withScope(() => {
+      this.declareParams(node.params)
+      this.emitFunctionBody(node)
+    })
+    this.line('}')
+    this.applyDecorators(node.name, node.decorators)
+  }
+
+  private emitClassDecl(node: ClassDecl, exported: boolean): void {
+    if (node.doc) this.emitDoc(node.doc)
+    this.emitDecorators(node.decorators)
+    this.declare(node.name)
+
+    const prefix = exported ? 'export ' : ''
+    const parent = node.superClass ? ` extends ${node.superClass}` : ''
+    this.line(`${prefix}class ${node.name}${parent} {`)
+    const methodWrappers: Array<{ target: string, decorators: Decorator[] }> = []
+    this.withScope(() => {
+      for (const member of node.members) {
+        if (member.kind === 'VarDecl') {
+          if (member.doc) this.emitDoc(member.doc)
+          this.emitDecorators(member.decorators)
+          member.names.forEach((entry, index) => {
+            const value = member.values[index]
+            this.line(`${entry.name} = ${value ? this.expr(value) : 'undefined'};`)
+            this.declare(entry.name)
+          })
+          continue
+        }
+        this.emitClassMethod(member)
+        if (member.decorators.length) {
+          if (member.name === 'init') {
+            // Constructors cannot be reassigned after the class is built.
+            this.emitDecorators(member.decorators)
+          } else {
+            methodWrappers.push({
+              target: `${node.name}.prototype.${propertyName(member.name)}`,
+              decorators: member.decorators,
+            })
+          }
+        }
+      }
+    })
+    this.line('}')
+    for (const wrapper of methodWrappers) {
+      this.emitDecorators(wrapper.decorators)
+      this.applyDecorators(wrapper.target, wrapper.decorators)
+    }
+    this.applyDecorators(node.name, node.decorators)
+  }
+
+  private emitClassMethod(node: FnDecl): void {
+    if (node.doc) this.emitDoc(node.doc)
+    const name = node.name === 'init' ? 'constructor' : node.name
+    const asyncKeyword = node.async && name !== 'constructor' ? 'async ' : ''
+    this.line(`${asyncKeyword}${name}(${this.emitParams(node.params)}) {`)
+    this.withScope(() => {
+      this.declareParams(node.params)
+      this.emitFunctionBody(node)
+    })
+    this.line('}')
+  }
+
+  private emitFunctionBody(node: FnDecl | FunctionExpr): void {
+    if (node.exprBody) {
+      this.line(`return ${this.expr(node.exprBody)};`)
+      return
+    }
+    this.emitBlock(node.body)
+  }
+
+  private declareParams(params: Param[]): void {
+    for (const param of params) this.declare(rawParamName(param))
+  }
+
+  private emitParams(params: Param[]): string {
+    return params.map((param) => {
+      if (param.rest) return `...${rawParamName(param)}`
+      const value = param.default ? ` = ${this.expr(param.default)}` : ''
+      return `${param.name}${value}`
+    }).join(', ')
+  }
+
+  private renderFunction(node: FnDecl | FunctionExpr): string {
+    const sub = new Emitter(this.options)
+    sub.scopes = [new Set()]
+    const params = sub.emitParams(node.params)
+    sub.withScope(() => {
+      sub.declareParams(node.params)
+      sub.emitFunctionBody(node)
+    })
+    const body = sub.lines.map(text => (text ? this.pad() + text : text)).join('\n')
+    const asyncKeyword = node.async ? 'async ' : ''
+    return `${asyncKeyword}function (${params}) {\n${body}\n${this.pad()}}`
+  }
+
+  private emitTypeAlias(node: TypeAliasDecl, exported: boolean): void {
+    if (node.doc) this.emitDoc(node.doc)
+    this.line(`${exported ? 'export ' : ''}type ${node.name} = ${typeAnn(node.type)};`)
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Control flow                                                      */
+  /* ---------------------------------------------------------------- */
+
+  private emitIf(node: Extract<Statement, { kind: 'IfStmt' }>): void {
+    this.line(`if (${this.expr(node.cond)}) {`)
+    this.withScope(() => this.emitBlock(node.then))
+    for (const branch of node.elifs) {
+      this.line(`} else if (${this.expr(branch.cond)}) {`)
+      this.withScope(() => this.emitBlock(branch.body))
+    }
+    if (node.else) {
+      this.line('} else {')
+      this.withScope(() => this.emitBlock(node.else))
+    }
+    this.line('}')
+  }
+
+  private emitForNumeric(node: ForNumeric): void {
+    const from = this.expr(node.from)
+    const to = this.expr(node.to)
+    const step = node.step ? this.expr(node.step) : '1'
+    const descending = isNegative(node.step)
+    const compare = descending ? '>=' : '<='
+    this.line(`for (let ${node.varName} = ${from}; ${node.varName} ${compare} ${to}; ${node.varName} += ${step}) {`)
+    this.withScope(() => {
+      this.declare(node.varName)
+      this.emitBlock(node.body)
+    })
+    this.line('}')
+  }
+
+  private emitForIn(node: ForIn): void {
+    let source: string
+    if (node.iter.kind === 'Range') {
+      source = `__spak.range(${this.expr(node.iter.from)}, ${this.expr(node.iter.to)}, ${node.iter.inclusive ? 'true' : 'false'})`
+    } else {
+      source = this.expr(node.iter)
+    }
+
+    if (node.vars.length > 1) {
+      this.line(`for (const [${node.vars.join(', ')}] of __spak.entries(${source})) {`)
+    } else {
+      this.line(`for (const ${node.vars[0]} of ${source}) {`)
+    }
+    this.withScope(() => {
+      for (const name of node.vars) this.declare(name)
+      this.emitBlock(node.body)
+    })
+    this.line('}')
+  }
+
+  private emitMatch(node: MatchStmt): void {
+    const subject = `__match${++this.temp}`
+    this.line(`const ${subject} = ${this.expr(node.subject)};`)
+
+    node.arms.forEach((arm, index) => {
+      const bindings: string[] = []
+      const conditions = arm.patterns.map((pattern) => {
+        if (pattern.kind === 'Ident') {
+          bindings.push(pattern.name)
+          return 'true'
+        }
+        return this.matchCondition(pattern, subject)
+      })
+      let condition = conditions.length ? conditions.join(' || ') : 'true'
+      if (arm.guard) condition = `(${condition} && (${this.expr(arm.guard)}))`
+      for (const name of bindings) condition = `((${name}) => ${condition})(${subject})`
+
+      this.line(`${index === 0 ? 'if' : '} else if'} (${condition}) {`)
+      this.withScope(() => {
+        for (const name of bindings) {
+          this.line(`const ${name} = ${subject};`)
+          this.declare(name)
+        }
+        this.emitBlock(arm.body)
+      })
+    })
+
+    if (node.elseBody) {
+      const hasArms = node.arms.length > 0
+      this.line(hasArms ? '} else {' : 'if (true) {')
+      this.withScope(() => this.emitBlock(node.elseBody))
+    }
+
+    if (node.arms.length || node.elseBody) this.line('}')
+  }
+
+  private matchCondition(pattern: Expr, subject: string): string {
+    if (pattern.kind === 'Range') {
+      const from = this.expr(pattern.from)
+      const to = this.expr(pattern.to)
+      const op = pattern.inclusive ? '<=' : '<'
+      return `(${subject} >= ${from} && ${subject} ${op} ${to})`
+    }
+    return `${subject} === ${this.expr(pattern)}`
+  }
+
+  private emitTry(node: TryStmt): void {
+    this.line('try {')
+    this.withScope(() => this.emitBlock(node.body))
+    if (node.catchBody) {
+      this.line(node.catchVar ? `} catch (${node.catchVar}) {` : '} catch {')
+      this.withScope(() => {
+        if (node.catchVar) this.declare(node.catchVar)
+        this.emitBlock(node.catchBody)
+      })
+    }
+    if (node.finallyBody) {
+      this.line('} finally {')
+      this.withScope(() => this.emitBlock(node.finallyBody))
+    }
+    this.line('}')
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Modules                                                           */
+  /* ---------------------------------------------------------------- */
+
+  private emitImport(node: ImportDecl): void {
+    if (node.doc) this.emitDoc(node.doc)
+    if (FS_SOURCES.has(node.source)) {
+      this.emitFsImport(node)
+      return
+    }
+    const source = JSON.stringify(node.source)
+    const form = node.form ?? inferImportForm(node)
+    if (node.clauses.length === 0 || form === 'side-effect') {
+      this.line(`import ${source};`)
+      return
+    }
+    if (form === 'namespace' || node.clauses[0]?.name === '*') {
+      const clause = node.clauses[0]
+      this.line(`import * as ${clause.alias ?? 'ns'} from ${source};`)
+      this.declare(clause.alias ?? 'ns')
+      return
+    }
+    if (form === 'default' && node.clauses.length === 1) {
+      const clause = node.clauses[0]
+      this.line(`import ${clause.name} from ${source};`)
+      this.declare(clause.name)
+      return
+    }
+    const specifiers = node.clauses.map(clause => clause.alias ? `${clause.name} as ${clause.alias}` : clause.name)
+    this.line(`import { ${specifiers.join(', ')} } from ${source};`)
+    for (const clause of node.clauses) this.declare(clause.alias ?? clause.name)
+  }
+
+  /**
+   * Spak's `fs` keeps the Lua-flavoured synchronous surface for backwards
+   * compatibility (`for name in readdir(dir)` in hello.spk), but named imports
+   * that are awaited bind to `node:fs/promises` instead:
+   *
+   *   import { readFile } from "fs"
+   *   text = await readFile("a.txt")     ->  node:fs/promises
+   *
+   * Synchronous access is explicit via `import { readFileSync } from "fs"`.
+   */
+  private emitFsImport(node: ImportDecl): void {
+    const form = node.form ?? inferImportForm(node)
+    if (node.clauses.length === 0 || form === 'side-effect') {
+      this.line('import "node:fs";')
+      return
+    }
+
+    const namespace = `__fs${++this.temp}`
+
+    if (form === 'namespace' || node.clauses[0]?.name === '*') {
+      const clause = node.clauses[0]
+      const alias = clause.alias ?? 'fs'
+      this.line(`import * as ${namespace} from "node:fs";`)
+      this.line(`const ${alias} = ${namespace};`)
+      this.declare(alias)
+      return
+    }
+
+    // `import fs from "fs"` historically exposed the whole namespace.
+    if (form === 'default' && node.clauses.length === 1) {
+      const clause = node.clauses[0]
+      this.line(`import * as ${namespace} from "node:fs";`)
+      this.line(`const ${clause.name} = ${namespace};`)
+      this.declare(clause.name)
+      return
+    }
+
+    const bindings: string[] = []
+    const asyncSpecifiers: string[] = []
+    for (const clause of node.clauses) {
+      if (clause.name === '*') {
+        bindings.push(`const ${clause.alias ?? 'fs'} = ${namespace};`)
+        this.declare(clause.alias ?? 'fs')
+        continue
+      }
+      const local = clause.alias ?? clause.name
+      const member = fsMember(clause.name, this.awaited.has(local))
+      if (member.namespace === 'async') {
+        asyncSpecifiers.push(clause.alias ? `${clause.name} as ${clause.alias}` : clause.name)
+        this.declare(local)
+        continue
+      }
+      if (member.renamed) {
+        bindings.push(`// fs compat: never awaited, bound to ${member.name}; use import { ${member.name} } for an explicit sync API`)
+      }
+      bindings.push(`const ${local} = ${namespace}.${member.name};`)
+      this.declare(local)
+    }
+
+    if (bindings.length) this.line(`import * as ${namespace} from "node:fs";`)
+    if (asyncSpecifiers.length) this.line(`import { ${asyncSpecifiers.join(', ')} } from "node:fs/promises";`)
+    for (const binding of bindings) this.line(binding)
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Expressions                                                       */
+  /* ---------------------------------------------------------------- */
+
+  private expr(node: Expr): string {
+    switch (node.kind) {
+      case 'NumberLit':
+        return Number.isFinite(node.value) ? String(node.value) : '0'
+      case 'StringLit':
+        return this.string(node)
+      case 'BoolLit':
+        return node.value ? 'true' : 'false'
+      case 'NilLit':
+        return 'null'
+      case 'Ident':
+        return (node as Ident).name
+      case 'SelfExpr':
+        return 'this'
+      case 'Member':
+        return `${this.expr(node.object)}${node.optional ? '?.' : '.'}${propertyName(node.property)}`
+      case 'Index':
+        return this.index(node)
+      case 'Call':
+        return this.call(node)
+      case 'Binary':
+        return this.binary(node)
+      case 'Unary':
+        if (node.op === 'not') return `(!(${this.expr(node.argument)}))`
+        if (node.op === '#') return `__spak.len(${this.expr(node.argument)})`
+        return `(-(${this.expr(node.argument)}))`
+      case 'Table':
+        return this.table(node)
+      case 'FunctionExpr':
+        return this.renderFunction(node)
+      case 'Range':
+        return `__spak.range(${this.expr(node.from)}, ${this.expr(node.to)}, ${node.inclusive ? 'true' : 'false'})`
+      case 'AwaitExpr':
+        return `(await ${this.expr(node.argument)})`
+      case 'Spread':
+        return node.argument ? `...${this.expr(node.argument)}` : '...[]'
+      default:
+        return 'undefined'
+    }
+  }
+
+  private string(node: StringLit): string {
+    if (node.fstring && node.parts) {
+      const body = node.parts.map((part) => {
+        if (typeof part === 'string') return escapeTemplate(part)
+        return `\${${this.expr(part)}}`
+      }).join('')
+      return `\`${body}\``
+    }
+    return JSON.stringify(node.value)
+  }
+
+  private index(node: Index): string {
+    const object = this.expr(node.object)
+    if (node.index.kind === 'Range') {
+      const range = node.index
+      // `list[1..n]` is the common case: a plain 0-based slice. Everything
+      // else (including `..<` and empty `1..0`) goes through the clamped
+      // runtime helper so an off-by-one end can never wrap from the tail.
+      if (range.from.kind === 'NumberLit' && range.from.value === 1 && range.inclusive) {
+        return `${object}.slice(0, ${this.expr(range.to)})`
+      }
+      return `__spak.slice(${object}, ${this.expr(range.from)}, ${this.expr(range.to)}, ${range.inclusive ? 'true' : 'false'})`
+    }
+    return `__spak.idx(${object}, ${this.expr(node.index)})`
+  }
+
+  private call(node: Call, prepend: Expr[] = []): string {
+    const args = [...prepend, ...node.args].map(arg => this.expr(arg)).join(', ')
+
+    if (node.callee.kind === 'Member') {
+      const member = node.callee
+      const object = this.expr(member.object)
+      if (!node.isMethod && member.property === 'new') {
+        return `new ${object}(${args})`
+      }
+      if (node.isMethod && RUNTIME_METHODS.has(member.property)) {
+        const prefix = args ? `${object}, ${args}` : object
+        return `__spak.${member.property}(${prefix})`
+      }
+      const access = `${object}${member.optional ? '?.' : '.'}${propertyName(member.property)}`
+      return `${access}(${args})`
+    }
+
+    if (node.callee.kind === 'Ident') {
+      if (node.callee.name === 'len') return `__spak.len(${args})`
+      if (node.callee.name === 'range') return `__spak.range(${args})`
+      if (node.callee.name === 'pairs' || node.callee.name === 'ipairs') return `__spak.entries(${args})`
+    }
+
+    return `${this.expr(node.callee)}(${args})`
+  }
+
+  private binary(node: Extract<Expr, { kind: 'Binary' }>): string {
+    const left = this.expr(node.left)
+    const right = this.expr(node.right)
+
+    if (node.op === '|>') {
+      if (node.right.kind === 'Call') return this.call(node.right, [node.left])
+      return `${this.expr(node.right)}(${left})`
+    }
+    if (node.op === '//') return `Math.floor((${left}) / (${right}))`
+    if (node.op === '..') return `(String(${left}) + String(${right}))`
+
+    const operators: Record<string, string> = {
+      and: '&&',
+      or: '||',
+      '==': '===',
+      '~=': '!==',
+      '^': '**',
+    }
+    const operator = operators[node.op] ?? node.op
+    return `(${left} ${operator} ${right})`
+  }
+
+  private table(node: Table): string {
+    if (node.fields.length === 0) return '[]'
+    const hasKeys = node.fields.some(field => field.key)
+
+    if (!hasKeys) {
+      return `[${node.fields.map(field => this.expr(field.value)).join(', ')}]`
+    }
+
+    const parts: string[] = []
+    let position = 0
+    for (const field of node.fields) {
+      if (field.key?.kind === 'Ident') {
+        parts.push(`${propertyName(field.key.name)}: ${this.expr(field.value)}`)
+        continue
+      }
+      if (field.key) {
+        parts.push(`[${this.expr(field.key)}]: ${this.expr(field.value)}`)
+        continue
+      }
+      parts.push(`${position}: ${this.expr(field.value)}`)
+      position++
+    }
+    return `{ ${parts.join(', ')} }`
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+/** Falls back to the historical clause-shape inference for hand-built ASTs. */
+function inferImportForm(node: ImportDecl): ImportForm {
+  if (!node.clauses.length) return 'side-effect'
+  if (node.clauses.length > 1) return 'named'
+  if (node.clauses[0].name === '*') return 'namespace'
+  return 'default'
+}
+
+interface FsMember {
+  /** Property read from the `node:fs` / `node:fs/promises` namespace. */
+  name: string
+  namespace: 'sync' | 'async'
+  /** True when a non-awaited function was rewritten to its `*Sync` twin. */
+  renamed: boolean
+}
+
+/**
+ * Resolves how an `fs` named import is bound:
+ * - `readFileSync` -> `readFileSync` on `node:fs` (explicit sync)
+ * - `readFile` awaited -> `readFile` on `node:fs/promises`
+ * - `readFile` not awaited -> `readFileSync` on `node:fs` (compat)
+ */
+function fsMember(name: string, awaited: boolean): FsMember {
+  if (name.endsWith('Sync') || !FS_SYNC.has(name)) {
+    return { name, namespace: 'sync', renamed: false }
+  }
+  if (awaited) return { name, namespace: 'async', renamed: false }
+  return { name: `${name}Sync`, namespace: 'sync', renamed: true }
+}
+
+/** Collects identifiers used directly under `await` (`await readFile(...)`). */
+function collectAwaitedIdentifiers(program: Program): Set<string> {
+  const names = new Set<string>()
+
+  // Every identifier inside the awaited expression is a candidate; only fs
+  // names are consulted later, so unrelated identifiers are harmless.
+  const collectFrom = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return
+    if (Array.isArray(node)) {
+      for (const item of node) collectFrom(item)
+      return
+    }
+    const candidate = node as { kind?: string, name?: string }
+    if (candidate.kind === 'Ident' && candidate.name) names.add(candidate.name)
+    for (const child of Object.values(node)) collectFrom(child)
+  }
+
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') return
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item)
+      return
+    }
+    const node = value as { kind?: string, argument?: unknown }
+    if (node.kind === 'AwaitExpr') collectFrom(node.argument)
+    for (const child of Object.values(value)) visit(child)
+  }
+
+  visit(program)
+  return names
+}
+
+function rawParamName(param: Param): string {
+  return param.rest ? (param.name === '...' ? 'args' : param.name) : param.name
+}
+
+function propertyName(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name)
+}
+
+function isNegative(expr: Expr | undefined): boolean {
+  if (!expr) return false
+  if (expr.kind === 'NumberLit') return expr.value < 0
+  return expr.kind === 'Unary' && expr.op === '-' && expr.argument.kind === 'NumberLit'
+}
+
+function escapeTemplate(text: string): string {
+  return text.replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+}
+
+/** Converts a Spak type annotation into TypeScript syntax (types only). */
+export function typeAnn(node: TypeAnn): string {
+  switch (node.kind) {
+    case 'named':
+      return node.name === 'nil' ? 'null' : node.name
+    case 'array': {
+      const element = node.element.kind === 'union' || node.element.kind === 'fn'
+        ? `(${typeAnn(node.element)})`
+        : typeAnn(node.element)
+      return `${element}[]`
+    }
+    case 'dict':
+      return `Record<${typeAnn(node.key)}, ${typeAnn(node.value)}>`
+    case 'record':
+      return `{ ${node.fields.map(field => `${propertyName(field.name)}: ${typeAnn(field.type)}`).join(', ')} }`
+    case 'union':
+      return node.types.map(typeAnn).join(' | ')
+    case 'fn':
+      return `(${node.params.map(typeAnn).join(', ')}) => ${typeAnn(node.returns)}`
+    case 'optional':
+      return `${typeAnn(node.type)} | null`
+    default:
+      return 'unknown'
+  }
+}
+
+/** Lowers a Spak program to an executable ESM TypeScript module. */
+export function emitTypeScript(program: Program, options: EmitOptions = {}): string {
+  return new Emitter(options).emitProgram(program)
+}