xbintsc 0.2.8 → 0.3.1

package/src/binder/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Binder data model: the plain-data symbols, scopes and per-function records
+ * that the binder produces and the checker/codegen consume.
+ */
+
+import type {
+  ArrowFunction,
+  Expression,
+  FunctionDeclaration,
+  FunctionExpression,
+  Identifier,
+  Node,
+  SourceFileNode,
+} from "../ast/nodes.js";
+
+export enum SymbolKind {
+  Var = "var",
+  Let = "let",
+  Const = "const",
+  Function = "function",
+  Parameter = "parameter",
+  Class = "class",
+  Interface = "interface",
+  TypeAlias = "type",
+  Enum = "enum",
+  Import = "import",
+  Namespace = "namespace",
+}
+
+export interface SymbolInfo {
+  readonly id: number;
+  readonly name: string;
+  readonly kind: SymbolKind;
+  /** False for `const` bindings and imports. */
+  readonly mutable: boolean;
+  /** The function this symbol belongs to. */
+  readonly fn: FunctionInfo;
+  readonly declarations: Node[];
+  readonly references: Identifier[];
+  /** Set when referenced from a nested function. */
+  captured: boolean;
+  /** Assigned after construction once we know it is captured. */
+  boxed: boolean;
+}
+
+export type FunctionNode = SourceFileNode | FunctionDeclaration | FunctionExpression | ArrowFunction;
+
+export interface FunctionInfo {
+  readonly id: number;
+  readonly name: string;
+  readonly node: FunctionNode;
+  readonly parent?: FunctionInfo;
+  readonly scope: Scope;
+  readonly params: SymbolInfo[];
+  /** Every binding declared directly in this function (params + locals). */
+  readonly locals: SymbolInfo[];
+  /** Outer bindings referenced by this function or any descendant. */
+  readonly captures: SymbolInfo[];
+  readonly captureIndex: Map<number, number>;
+  readonly isModule: boolean;
+  readonly isArrow: boolean;
+  /** True when the function was declared `async`. */
+  readonly isAsync: boolean;
+  /** True when this function's body mentions `this` directly. */
+  usesThis: boolean;
+  /** True when an arrow function must receive `this` from its enclosing scope. */
+  capturesThis: boolean;
+  /** Set for class methods/constructors; carries the owning class. */
+  classInfo?: ClassInfo;
+  /** True for `static` class members. */
+  isStatic?: boolean;
+  /** True for an explicit `constructor`. */
+  isConstructor?: boolean;
+}
+
+export interface ClassInfo {
+  readonly id: number;
+  readonly name: string;
+  readonly node: Node;
+  readonly scope: Scope;
+  readonly parent?: ClassInfo;
+  readonly parentExpression?: Expression;
+  /** `this`-bearing fields declared on the class. */
+  readonly fields: ClassFieldInfo[];
+  readonly methods: FunctionInfo[];
+  readonly statics: FunctionInfo[];
+  ctor?: FunctionInfo;
+  /** The symbol the class name binds to, when there is one. */
+}
+
+export interface ClassFieldInfo {
+  readonly name: string;
+  readonly initializer: Expression | undefined;
+  readonly fn: FunctionInfo;
+  readonly isStatic: boolean;
+}
+
+export enum ScopeKind {
+  Module = "module",
+  Function = "function",
+  Block = "block",
+  For = "for",
+  Catch = "catch",
+}
+
+export interface Scope {
+  readonly kind: ScopeKind;
+  readonly parent?: Scope;
+  readonly fn: FunctionInfo;
+  readonly symbols: Map<string, SymbolInfo>;
+  /** The syntax node that introduced the scope, when there is one. */
+  readonly node?: Node;
+}
+
+export interface BindResult {
+  readonly moduleFunction: FunctionInfo;
+  readonly functions: FunctionInfo[];
+  readonly classes: ClassInfo[];
+  /** Maps a class-like AST node to the ClassInfo the binder built. */
+  readonly classOfNode: Map<Node, ClassInfo>;
+  /** Maps a function-like AST node to the FunctionInfo the binder built for it. */
+  readonly functionOfNode: Map<Node, FunctionInfo>;
+  readonly symbolOfDeclaration: Map<Node, SymbolInfo>;
+  readonly symbolOfIdentifier: Map<Identifier, SymbolInfo>;
+  readonly scopes: Map<Node, Scope>;
+  /** Identifier references that could not be resolved in user code. */
+  readonly unresolved: Identifier[];
+}
+
+export interface MutableFunction extends FunctionInfo {
+  locals: SymbolInfo[];
+  captures: SymbolInfo[];
+  captureIndex: Map<number, number>;
+}

package/src/cli/main.ts

@@ -7,6 +7,7 @@
  *   xbintsc build <file> [-o out] [--emit ir|obj|exe] [-O0..3] [--ext node]
  *   xbintsc run   <file> [-- args...]
  *   xbintsc emit  <file>            # print LLVM IR to stdout
+ *   xbintsc doctor                  # report the resolved toolchain
  *   xbintsc version
  */
 
@@ -17,6 +18,10 @@ import { pathToFileURL } from "node:url";
 import { DiagnosticBag, formatDiagnostic, type Diagnostic } from "../diagnostics/diagnostic.js";
 import { SourceFile } from "../diagnostics/source.js";
 import { build, compileEntry, COMPILER_VERSION, type EmitKind } from "../driver/compiler.js";
+import { findRuntimeDir, platformSlug } from "../driver/paths.js";
+import { runtimeLibDir } from "../driver/runtime-lib.js";
+import { resolveToolchain } from "../driver/toolchain-provider.js";
+import { realRunner } from "../driver/toolchain.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
 import { nodeExtension } from "../extensions/node/index.js";
 
@@ -119,6 +124,7 @@ Usage:
   xbintsc build <file.ts> [options]   Compile to a native binary
   xbintsc run <file.ts> [-- args]     Compile and execute
   xbintsc emit <file.ts>              Print LLVM IR
+  xbintsc doctor                      Report the resolved toolchain
   xbintsc version                     Print the version
   xbintsc help                        Show this message
 
@@ -132,6 +138,39 @@ Options:
       --verbose         Print progress information
 `;
 
+function firstLine(text: string): string {
+  const index = text.indexOf("\n");
+  return (index === -1 ? text : text.slice(0, index)).trim();
+}
+
+/** Report the resolved toolchain and runtime locations. */
+function doctor(io: CliIo): number {
+  io.stdout(`xbintsc ${COMPILER_VERSION}\n`);
+  io.stdout(`platform   : ${platformSlug()}\n`);
+
+  try {
+    const toolchain = resolveToolchain();
+    const version = realRunner.run(toolchain.clang, ["--version"], { env: toolchain.env }).stdout;
+    io.stdout(`toolchain  : ${toolchain.clang} (${toolchain.source})\n`);
+    io.stdout(`compiler   : ${firstLine(version) || "unknown"}\n`);
+  } catch {
+    io.stdout("toolchain  : not found (install the Xcode Command Line Tools or set xbintsc_CLANG)\n");
+  }
+
+  try {
+    io.stdout(`runtime    : ${findRuntimeDir()}\n`);
+  } catch {
+    io.stdout("runtime    : not found (cannot locate runtime/rt.h)\n");
+  }
+
+  try {
+    io.stdout(`runtime lib: ${runtimeLibDir()}\n`);
+  } catch {
+    io.stdout("runtime lib: unavailable\n");
+  }
+  return 0;
+}
+
 export function run(argv: readonly string[], io: CliIo = defaultIo): number {
   const args = parseArgs(argv);
   const command = args.command;
@@ -141,6 +180,10 @@ export function run(argv: readonly string[], io: CliIo = defaultIo): number {
     return 0;
   }
 
+  if (command === "doctor") {
+    return doctor(io);
+  }
+
   if (command === "version" || args.flags.has("version")) {
     io.stdout(`xbintsc ${COMPILER_VERSION}\n`);
     return 0;

package/src/codegen/generator/calls/access.ts

@@ -0,0 +1,139 @@
+/**
+ * Member access lowering: property/element reads, `delete` and optional
+ * chaining guards.
+ */
+
+import {
+  SyntaxKind,
+  type DeleteExpression,
+  type ElementAccessExpression,
+  type Identifier,
+  type PropertyAccessExpression,
+} from "../../../ast/nodes.js";
+import { i64, numberLiteral, XT_TRUE, XT_UNDEFINED } from "../../values.js";
+import { MATH_CONSTANTS, NAMESPACE_PROPERTIES } from "../tables.js";
+import type { Generator } from "../generator.js";
+
+export interface AccessCallMethods {
+  emitDelete(this: Generator, node: DeleteExpression): string;
+  emitPropertyAccess(this: Generator, node: PropertyAccessExpression): string;
+  emitElementAccess(this: Generator, node: ElementAccessExpression): string;
+  emitOptional(this: Generator, objectValue: string, compute: () => string): string;
+}
+
+export const accessCallMethods: AccessCallMethods = {
+  emitDelete(node: DeleteExpression): string {
+    const target = node.expression;
+    if (target.kind === SyntaxKind.PropertyAccessExpression) {
+      const access = target as PropertyAccessExpression;
+      const object = this.emitExpression(access.expression);
+      const key = this.stringValue(access.name.text);
+      return this.runtimeCall("xt_delete", [object, key]);
+    }
+    if (target.kind === SyntaxKind.ElementAccessExpression) {
+      const access = target as ElementAccessExpression;
+      const object = this.emitExpression(access.expression);
+      const key = this.emitExpression(access.argumentExpression);
+      return this.runtimeCall("xt_delete", [object, key]);
+    }
+    return i64(XT_TRUE);
+  },
+
+  emitPropertyAccess(node: PropertyAccessExpression): string {
+    if (node.expression.kind === SyntaxKind.Identifier && (node.expression as Identifier).text === "super") {
+      const thisValue = this.emitThis();
+      const proto = this.reg();
+      this.emit(`  ${proto} = call i64 @xt_object_get_prototype(i64 ${thisValue})`);
+      const parentProto = this.reg();
+      this.emit(`  ${parentProto} = call i64 @xt_object_get_prototype(i64 ${proto})`);
+      const key = this.stringValue(node.name.text);
+      const value = this.reg();
+      this.emit(`  ${value} = call i64 @xt_get(i64 ${parentProto}, i64 ${key})`);
+      return value;
+    }
+    if (
+      node.name.text in MATH_CONSTANTS &&
+      node.expression.kind === SyntaxKind.Identifier &&
+      (node.expression as Identifier).text === "Math" &&
+      !this.binding.symbolOfIdentifier.get(node.expression as Identifier)
+    ) {
+      return numberLiteral(MATH_CONSTANTS[node.name.text]!);
+    }
+    if (
+      node.expression.kind === SyntaxKind.Identifier &&
+      !this.binding.symbolOfIdentifier.get(node.expression as Identifier)
+    ) {
+      const getter = NAMESPACE_PROPERTIES[(node.expression as Identifier).text];
+      if (getter) {
+        const key = this.stringValue(node.name.text);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${getter}(i64 ${key})`);
+        return result;
+      }
+    }
+    if (node.expression.kind === SyntaxKind.Identifier) {
+      const namespace = this.namespaceOfSymbol(
+        this.binding.symbolOfIdentifier.get(node.expression as Identifier),
+      );
+      if (namespace) {
+        const getter = NAMESPACE_PROPERTIES[namespace];
+        if (getter) {
+          const key = this.stringValue(node.name.text);
+          const result = this.reg();
+          this.emit(`  ${result} = call i64 @${getter}(i64 ${key})`);
+          return result;
+        }
+      }
+    }
+    const object = this.emitExpression(node.expression);
+    const access = (): string => {
+      if (node.name.text === "length") {
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @xt_array_length(i64 ${object})`);
+        return result;
+      }
+      const key = this.stringValue(node.name.text);
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @xt_get(i64 ${object}, i64 ${key})`);
+      return result;
+    };
+    return node.optional ? this.emitOptional(object, access) : access();
+  },
+
+  emitElementAccess(node: ElementAccessExpression): string {
+    const object = this.emitExpression(node.expression);
+    const access = (): string => {
+      const key = this.emitExpression(node.argumentExpression);
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @xt_get(i64 ${object}, i64 ${key})`);
+      return result;
+    };
+    return node.optional ? this.emitOptional(object, access) : access();
+  },
+
+  /**
+   * Evaluate `object` once and, when it is neither `null` nor `undefined`, run
+   * `compute` to produce the value; otherwise short-circuit to `undefined`.
+   */
+  emitOptional(objectValue: string, compute: () => string): string {
+    const result = this.alloca();
+    this.emit(`  store i64 ${i64(XT_UNDEFINED)}, i64* ${result}`);
+    const nullish = this.reg();
+    this.emit(`  ${nullish} = call i64 @xt_is_nullish(i64 ${objectValue})`);
+    const truthy = this.reg();
+    this.emit(`  ${truthy} = call i32 @xt_truthy(i64 ${nullish})`);
+    const condition = this.reg();
+    this.emit(`  ${condition} = icmp ne i32 ${truthy}, 0`);
+    const someLabel = this.label("opt.some");
+    const endLabel = this.label("opt.end");
+    this.terminate(`br i1 ${condition}, label %${endLabel}, label %${someLabel}`);
+    this.startBlock(someLabel);
+    const value = compute();
+    this.emit(`  store i64 ${value}, i64* ${result}`);
+    this.terminate(`br label %${endLabel}`);
+    this.startBlock(endLabel);
+    const merged = this.reg();
+    this.emit(`  ${merged} = load i64, i64* ${result}`);
+    return merged;
+  },
+};

package/src/codegen/generator/calls/closures.ts

@@ -0,0 +1,60 @@
+/**
+ * Closure lowering: arrow/function expressions and their captured environments.
+ */
+
+import type { ArrowFunction, FunctionExpression } from "../../../ast/nodes.js";
+import type { FunctionInfo } from "../../../binder/binder.js";
+import { i64, XT_UNDEFINED } from "../../values.js";
+import type { Generator } from "../generator.js";
+
+export interface ClosureCallMethods {
+  emitClosure(this: Generator, node: ArrowFunction | FunctionExpression): string;
+  emitClosureValue(this: Generator, fn: FunctionInfo): string;
+}
+
+export const closureCallMethods: ClosureCallMethods = {
+  emitClosure(node: ArrowFunction | FunctionExpression): string {
+    const fn = this.binding.functionOfNode.get(node);
+    if (!fn) {
+      this.unsupported(node, "closure");
+      return i64(XT_UNDEFINED);
+    }
+    return this.emitClosureValue(fn);
+  },
+
+  emitClosureValue(fn: FunctionInfo): string {
+    const count = fn.captures.length + (fn.capturesThis ? 1 : 0);
+    let envPtr = "null";
+    if (count > 0) {
+      envPtr = `%env${this.current.allocas.length}`;
+      this.current.allocas.push(`${envPtr} = alloca i64, i32 ${count}`);
+      for (let index = 0; index < fn.captures.length; index++) {
+        const symbol = fn.captures[index]!;
+        const slot = this.current.slots.get(symbol.id);
+        let raw = i64(XT_UNDEFINED);
+        if (slot) {
+          raw = this.reg();
+          this.emit(`  ${raw} = load i64, i64* ${slot.ptr}`);
+        }
+        const target = this.reg();
+        this.emit(`  ${target} = getelementptr i64, i64* ${envPtr}, i32 ${index}`);
+        this.emit(`  store i64 ${raw}, i64* ${target}`);
+      }
+      if (fn.capturesThis) {
+        let thisValue = i64(XT_UNDEFINED);
+        if (this.current.thisPtr) {
+          thisValue = this.reg();
+          this.emit(`  ${thisValue} = load i64, i64* ${this.current.thisPtr}`);
+        }
+        const target = this.reg();
+        this.emit(`  ${target} = getelementptr i64, i64* ${envPtr}, i32 ${fn.captures.length}`);
+        this.emit(`  store i64 ${thisValue}, i64* ${target}`);
+      }
+    }
+    const cast = this.reg();
+    this.emit(`  ${cast} = bitcast i64 (i64, i64, i32, i64*)* @${this.functionName(fn)} to i8*`);
+    const closure = this.reg();
+    this.emit(`  ${closure} = call i64 @xt_closure_new(i8* ${cast}, i32 ${count}, i64* ${envPtr})`);
+    return closure;
+  },
+};

package/src/codegen/generator/calls/invocation.ts

@@ -0,0 +1,282 @@
+/**
+ * Call invocation: direct calls, built-in/namespace dispatch, imported
+ * bindings, argument marshalling and generic runtime calls.
+ */
+
+import {
+  SyntaxKind,
+  type CallExpression,
+  type ElementAccessExpression,
+  type Expression,
+  type Identifier,
+  type PropertyAccessExpression,
+  type SpreadElement,
+} from "../../../ast/nodes.js";
+import { SymbolKind } from "../../../binder/binder.js";
+import type { ModuleExport } from "../../../extensions/registry.js";
+import { i64, XT_UNDEFINED } from "../../values.js";
+import {
+  BUILTIN_METHODS,
+  CONSOLE_METHODS,
+  CTOR_FUNCTIONS,
+  GLOBAL_FUNCTIONS,
+  MATH_FUNCTIONS,
+  NAMESPACE_STATICS,
+} from "../tables.js";
+import type { Generator } from "../generator.js";
+
+export interface InvocationCallMethods {
+  emitCall(this: Generator, node: CallExpression): string;
+  tryEmitBuiltinCall(this: Generator, node: CallExpression, callee: PropertyAccessExpression): string | undefined;
+  emitModuleExport(this: Generator, node: CallExpression, exported: ModuleExport): string;
+  runtimeCall(this: Generator, name: string, args: readonly string[]): string;
+  emitArguments(this: Generator, args: readonly Expression[]): { argc: string; ptr: string };
+}
+
+export const invocationCallMethods: InvocationCallMethods = {
+  emitCall(node: CallExpression): string {
+    const callee = node.expression;
+    if (node.optional) {
+      const calleeValue = this.emitExpression(callee);
+      return this.emitOptional(calleeValue, () => {
+        const args = this.emitArguments(node.arguments);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @xt_closure_call(i64 ${calleeValue}, i32 ${args.argc}, i64* ${args.ptr})`);
+        return result;
+      });
+    }
+    if (
+      (callee.kind === SyntaxKind.PropertyAccessExpression || callee.kind === SyntaxKind.ElementAccessExpression) &&
+      (callee as PropertyAccessExpression | ElementAccessExpression).optional
+    ) {
+      // `obj?.method(args)` / `obj?.[key](args)`: guard the receiver, then
+      // dispatch through the runtime, which understands object methods as well
+      // as the built-in array/string methods.
+      const access = callee as PropertyAccessExpression | ElementAccessExpression;
+      const object = this.emitExpression(access.expression);
+      return this.emitOptional(object, () => {
+        const name =
+          access.kind === SyntaxKind.PropertyAccessExpression
+            ? this.stringValue((access as PropertyAccessExpression).name.text)
+            : this.emitExpression((access as ElementAccessExpression).argumentExpression);
+        const args = this.emitArguments(node.arguments);
+        const result = this.reg();
+        this.emit(
+          `  ${result} = call i64 @xt_call_method(i64 ${object}, i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`,
+        );
+        return result;
+      });
+    }
+    if (callee.kind === SyntaxKind.PropertyAccessExpression) {
+      const access = callee as PropertyAccessExpression;
+      const special = this.tryEmitBuiltinCall(node, access);
+      if (special) return special;
+      if (access.expression.kind === SyntaxKind.Identifier && (access.expression as Identifier).text === "super") {
+        return this.emitSuperCall(node, access);
+      }
+      const object = this.emitExpression(access.expression);
+      const name = this.stringValue(access.name.text);
+      const args = this.emitArguments(node.arguments);
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @xt_call_method(i64 ${object}, i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`);
+      return result;
+    }
+    if (callee.kind === SyntaxKind.ElementAccessExpression) {
+      const access = callee as ElementAccessExpression;
+      const object = this.emitExpression(access.expression);
+      const name = this.emitExpression(access.argumentExpression);
+      const args = this.emitArguments(node.arguments);
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @xt_call_method(i64 ${object}, i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`);
+      return result;
+    }
+    if (callee.kind === SyntaxKind.Identifier) {
+      if ((callee as Identifier).text === "super") return this.emitSuperConstructor(node);
+      const symbol = this.binding.symbolOfIdentifier.get(callee as Identifier);
+      if (symbol && symbol.kind === SymbolKind.Import) {
+        const exported = this.importExports.get(symbol.id);
+        if (exported) return this.emitModuleExport(node, exported);
+      }
+      if (symbol && symbol.kind === SymbolKind.Function) {
+        const declaration = symbol.declarations[0];
+        const fn = declaration ? this.binding.functionOfNode.get(declaration) : undefined;
+        if (fn) {
+          const args = this.emitArguments(node.arguments);
+          const result = this.reg();
+          this.emit(
+            `  ${result} = call i64 @${this.functionName(fn)}(i64 ${i64(XT_UNDEFINED)}, i64 ${i64(XT_UNDEFINED)}, i32 ${args.argc}, i64* ${args.ptr})`,
+          );
+          return result;
+        }
+      }
+      const globalFunction = !symbol ? GLOBAL_FUNCTIONS[(callee as Identifier).text] : undefined;
+      if (globalFunction) {
+        const args = this.emitArguments(node.arguments);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${globalFunction}(i32 ${args.argc}, i64* ${args.ptr})`);
+        return result;
+      }
+      const builtin = this.builtins[(callee as Identifier).text];
+      if (!symbol && builtin) {
+        this.extraDeclarations.add(
+          builtin.returnVoid ? `declare void @${builtin.symbol}(i32, i64*)` : `declare i64 @${builtin.symbol}(i32, i64*)`,
+        );
+        const args = this.emitArguments(node.arguments);
+        if (builtin.returnVoid) {
+          this.emit(`  call void @${builtin.symbol}(i32 ${args.argc}, i64* ${args.ptr})`);
+          return i64(XT_UNDEFINED);
+        }
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${builtin.symbol}(i32 ${args.argc}, i64* ${args.ptr})`);
+        return result;
+      }
+      const ctor = !symbol ? CTOR_FUNCTIONS[(callee as Identifier).text] : undefined;
+      if (ctor) {
+        const args = this.emitArguments(node.arguments);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${ctor}(i32 ${args.argc}, i64* ${args.ptr})`);
+        return result;
+      }
+    }
+    const calleeValue = this.emitExpression(callee);
+    const args = this.emitArguments(node.arguments);
+    const result = this.reg();
+    this.emit(`  ${result} = call i64 @xt_closure_call(i64 ${calleeValue}, i32 ${args.argc}, i64* ${args.ptr})`);
+    return result;
+  },
+
+  tryEmitBuiltinCall(node: CallExpression, callee: PropertyAccessExpression): string | undefined {
+    const target = callee.expression;
+    const method = callee.name.text;
+    const targetIdentifier = target.kind === SyntaxKind.Identifier ? (target as Identifier) : undefined;
+    const targetSymbol = targetIdentifier ? this.binding.symbolOfIdentifier.get(targetIdentifier) : undefined;
+
+    if (targetIdentifier && targetIdentifier.text === "console" && !targetSymbol) {
+      const consoleFn = CONSOLE_METHODS[method];
+      if (consoleFn) {
+        const args = this.emitArguments(node.arguments);
+        this.emit(`  call void @${consoleFn}(i32 ${args.argc}, i64* ${args.ptr})`);
+        return i64(XT_UNDEFINED);
+      }
+      return undefined;
+    }
+
+    if (targetIdentifier && targetIdentifier.text === "Math" && !targetSymbol) {
+      if (!MATH_FUNCTIONS.has(method)) return undefined;
+      const name = this.stringValue(method);
+      const args = this.emitArguments(node.arguments);
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @xt_math_call(i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`);
+      return result;
+    }
+
+    if (targetIdentifier && targetIdentifier.text === "JSON" && !targetSymbol) {
+      const fn = method === "parse" ? "xt_json_parse" : method === "stringify" ? "xt_json_stringify" : undefined;
+      if (!fn) return undefined;
+      const args = this.emitArguments(node.arguments);
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @${fn}(i32 ${args.argc}, i64* ${args.ptr})`);
+      return result;
+    }
+
+    if (targetIdentifier && !targetSymbol) {
+      const dispatcher = NAMESPACE_STATICS[targetIdentifier.text];
+      if (dispatcher && targetIdentifier.text !== "Math" && targetIdentifier.text !== "JSON") {
+        const name = this.stringValue(method);
+        const args = this.emitArguments(node.arguments);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${dispatcher}(i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`);
+        return result;
+      }
+    }
+
+    // `import * as ns from "path"` (or a default import) aliases a runtime
+    // namespace: `ns.join(...)` lowers to the same dispatcher as `path.join`.
+    if (targetIdentifier) {
+      const namespace = this.namespaceOfSymbol(targetSymbol);
+      if (namespace) {
+        const dispatcher = NAMESPACE_STATICS[namespace];
+        if (dispatcher) {
+          const name = this.stringValue(method);
+          const args = this.emitArguments(node.arguments);
+          const result = this.reg();
+          this.emit(`  ${result} = call i64 @${dispatcher}(i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`);
+          return result;
+        }
+      }
+    }
+
+    void BUILTIN_METHODS;
+    return undefined;
+  },
+
+  /** Lower a call to an imported module binding to its runtime symbol. */
+  emitModuleExport(node: CallExpression, exported: ModuleExport): string {
+    const args = this.emitArguments(node.arguments);
+    if (exported.symbol) {
+      this.extraDeclarations.add(
+        exported.returnVoid
+          ? `declare void @${exported.symbol}(i32, i64*)`
+          : `declare i64 @${exported.symbol}(i32, i64*)`,
+      );
+      if (exported.returnVoid) {
+        this.emit(`  call void @${exported.symbol}(i32 ${args.argc}, i64* ${args.ptr})`);
+        return i64(XT_UNDEFINED);
+      }
+      const result = this.reg();
+      this.emit(`  ${result} = call i64 @${exported.symbol}(i32 ${args.argc}, i64* ${args.ptr})`);
+      return result;
+    }
+    if (exported.namespace && exported.method) {
+      const dispatcher = NAMESPACE_STATICS[exported.namespace];
+      if (dispatcher) {
+        const name = this.stringValue(exported.method);
+        const result = this.reg();
+        this.emit(`  ${result} = call i64 @${dispatcher}(i64 ${name}, i32 ${args.argc}, i64* ${args.ptr})`);
+        return result;
+      }
+    }
+    this.unsupported(node, "imported function");
+    return i64(XT_UNDEFINED);
+  },
+
+  runtimeCall(name: string, args: readonly string[]): string {
+    const result = this.reg();
+    this.emit(`  ${result} = call i64 @${name}(${args.map((a) => `i64 ${a}`).join(", ")})`);
+    return result;
+  },
+
+  emitArguments(args: readonly Expression[]): { argc: string; ptr: string } {
+    if (args.length === 0) return { argc: "0", ptr: "null" };
+    const hasSpread = args.some((element) => element.kind === SyntaxKind.SpreadElement);
+    if (!hasSpread) {
+      const ptr = `%args${this.current.allocas.length}`;
+      this.current.allocas.push(`${ptr} = alloca i64, i32 ${args.length}`);
+      for (let index = 0; index < args.length; index++) {
+        const value = this.emitExpression(args[index]!);
+        const slot = this.reg();
+        this.emit(`  ${slot} = getelementptr i64, i64* ${ptr}, i32 ${index}`);
+        this.emit(`  store i64 ${value}, i64* ${slot}`);
+      }
+      return { argc: String(args.length), ptr };
+    }
+    // At least one `...spread`: accumulate the argument list in a runtime
+    // array, which grows to whatever length the spread produces.
+    const array = this.reg();
+    this.emit(`  ${array} = call i64 @xt_array_new(i32 0, i64* null)`);
+    for (const element of args) {
+      if (element.kind === SyntaxKind.SpreadElement) {
+        const value = this.emitExpression((element as SpreadElement).expression);
+        this.emit(`  call i64 @xt_array_spread(i64 ${array}, i64 ${value})`);
+      } else {
+        const value = this.emitExpression(element);
+        this.emit(`  call i64 @xt_array_push(i64 ${array}, i64 ${value})`);
+      }
+    }
+    const argc = this.reg();
+    this.emit(`  ${argc} = call i32 @xt_array_size(i64 ${array})`);
+    const ptr = this.reg();
+    this.emit(`  ${ptr} = call i64* @xt_array_items(i64 ${array})`);
+    return { argc, ptr };
+  },
+};