@starpak/lang 0.0.0-stage → 0.1.3

package/lib/emit/ts.js

@@ -0,0 +1,950 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeAnn = typeAnn;
+exports.emitTypeScript = emitTypeScript;
+const version_1 = require("../version");
+/** 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 {
+    lines = [];
+    level = 0;
+    scopes = [new Set()];
+    temp = 0;
+    /** Identifiers used directly under `await`; drives the async `fs` surface. */
+    awaited = new Set();
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    get unit() {
+        return this.options.indent ?? '  ';
+    }
+    pad(extra = 0) {
+        return this.unit.repeat(Math.max(0, this.level + extra));
+    }
+    line(text = '') {
+        this.lines.push(text ? this.pad() + text : '');
+    }
+    withScope(fn) {
+        this.scopes.push(new Set());
+        this.level++;
+        try {
+            fn();
+        }
+        finally {
+            this.level--;
+            this.scopes.pop();
+        }
+    }
+    declare(name) {
+        this.scopes[this.scopes.length - 1].add(name);
+    }
+    declared(name) {
+        return this.scopes.some(scope => scope.has(name));
+    }
+    /* ---------------------------------------------------------------- */
+    /* Program                                                           */
+    /* ---------------------------------------------------------------- */
+    emitProgram(program) {
+        this.awaited = collectAwaitedIdentifiers(program);
+        for (const statement of program.body)
+            this.emitStatement(statement);
+        const chunks = [];
+        const defaultBanner = this.options.version
+            ? (0, version_1.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';
+    }
+    emitStatement(statement, exported = false) {
+        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.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.kind}`);
+        }
+    }
+    emitBlock(block) {
+        if (!block)
+            return;
+        for (const statement of block.body)
+            this.emitStatement(statement);
+    }
+    /** Comments only: used for positions that cannot be wrapped at runtime. */
+    emitDecorators(decorators) {
+        if (!decorators?.length)
+            return;
+        for (const decorator of decorators) {
+            this.line(`// @${decorator.name}${this.decoratorArgs(decorator)}`);
+        }
+    }
+    decoratorArgs(decorator) {
+        const args = decorator.args.map(arg => this.expr(arg)).join(', ');
+        return args ? `(${args})` : '';
+    }
+    /** Decorator as a callable expression: `memo`, `route("GET", "/x")`. */
+    decoratorCall(decorator) {
+        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)`.
+     */
+    applyDecorators(target, decorators) {
+        if (!decorators?.length)
+            return;
+        for (const decorator of [...decorators].reverse()) {
+            this.line(`${target} = ${this.decoratorCall(decorator)}(${target});`);
+        }
+    }
+    /* ---------------------------------------------------------------- */
+    /* Declarations                                                      */
+    /* ---------------------------------------------------------------- */
+    emitVarDecl(node, exported) {
+        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};`);
+            }
+        }
+    }
+    emitDoc(doc) {
+        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(' */');
+    }
+    emitAssign(node) {
+        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};`);
+        });
+    }
+    isPattern(target) {
+        return target.kind === 'TablePattern' || target.kind === 'ArrayPattern';
+    }
+    emitPatternAssign(pattern, value) {
+        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;
+        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);
+    }
+    emitFnDecl(node, exported) {
+        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);
+    }
+    emitClassDecl(node, exported) {
+        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 = [];
+        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);
+    }
+    emitClassMethod(node) {
+        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('}');
+    }
+    emitFunctionBody(node) {
+        if (node.exprBody) {
+            this.line(`return ${this.expr(node.exprBody)};`);
+            return;
+        }
+        this.emitBlock(node.body);
+    }
+    declareParams(params) {
+        for (const param of params)
+            this.declare(rawParamName(param));
+    }
+    emitParams(params) {
+        return params.map((param) => {
+            if (param.rest)
+                return `...${rawParamName(param)}`;
+            const value = param.default ? ` = ${this.expr(param.default)}` : '';
+            return `${param.name}${value}`;
+        }).join(', ');
+    }
+    renderFunction(node) {
+        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()}}`;
+    }
+    emitTypeAlias(node, exported) {
+        if (node.doc)
+            this.emitDoc(node.doc);
+        this.line(`${exported ? 'export ' : ''}type ${node.name} = ${typeAnn(node.type)};`);
+    }
+    /* ---------------------------------------------------------------- */
+    /* Control flow                                                      */
+    /* ---------------------------------------------------------------- */
+    emitIf(node) {
+        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('}');
+    }
+    emitForNumeric(node) {
+        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('}');
+    }
+    emitForIn(node) {
+        let source;
+        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('}');
+    }
+    emitMatch(node) {
+        const subject = `__match${++this.temp}`;
+        this.line(`const ${subject} = ${this.expr(node.subject)};`);
+        node.arms.forEach((arm, index) => {
+            const bindings = [];
+            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('}');
+    }
+    matchCondition(pattern, subject) {
+        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)}`;
+    }
+    emitTry(node) {
+        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                                                           */
+    /* ---------------------------------------------------------------- */
+    emitImport(node) {
+        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"`.
+     */
+    emitFsImport(node) {
+        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 = [];
+        const asyncSpecifiers = [];
+        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                                                       */
+    /* ---------------------------------------------------------------- */
+    expr(node) {
+        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.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';
+        }
+    }
+    string(node) {
+        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);
+    }
+    index(node) {
+        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)})`;
+    }
+    call(node, prepend = []) {
+        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})`;
+    }
+    binary(node) {
+        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 = {
+            and: '&&',
+            or: '||',
+            '==': '===',
+            '~=': '!==',
+            '^': '**',
+        };
+        const operator = operators[node.op] ?? node.op;
+        return `(${left} ${operator} ${right})`;
+    }
+    table(node) {
+        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 = [];
+        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) {
+    if (!node.clauses.length)
+        return 'side-effect';
+    if (node.clauses.length > 1)
+        return 'named';
+    if (node.clauses[0].name === '*')
+        return 'namespace';
+    return 'default';
+}
+/**
+ * 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, awaited) {
+    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) {
+    const names = new Set();
+    // Every identifier inside the awaited expression is a candidate; only fs
+    // names are consulted later, so unrelated identifiers are harmless.
+    const collectFrom = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                collectFrom(item);
+            return;
+        }
+        const candidate = node;
+        if (candidate.kind === 'Ident' && candidate.name)
+            names.add(candidate.name);
+        for (const child of Object.values(node))
+            collectFrom(child);
+    };
+    const visit = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        const node = value;
+        if (node.kind === 'AwaitExpr')
+            collectFrom(node.argument);
+        for (const child of Object.values(value))
+            visit(child);
+    };
+    visit(program);
+    return names;
+}
+function rawParamName(param) {
+    return param.rest ? (param.name === '...' ? 'args' : param.name) : param.name;
+}
+function propertyName(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function isNegative(expr) {
+    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) {
+    return text.replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+/** Converts a Spak type annotation into TypeScript syntax (types only). */
+function typeAnn(node) {
+    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. */
+function emitTypeScript(program, options = {}) {
+    return new Emitter(options).emitProgram(program);
+}
+//# sourceMappingURL=ts.js.map