compiler 0.0.2-preview.1

The Zena self-hosted compiler

Readme Files Dependencies Versions

compiler#

The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).

Usage#

Parsing a Single File#

Use compiler/parser to parse Zena source text into an AST (Module):

import { parse } from 'compiler/parser';

let ast = parse('export let answer = 42;', 'example.zena');

Loading and Checking a Program#

Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:

import {
  createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';

let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
  stdlibRoot,
  packages,
});

let result = await compiler.compile({
  entry: '/workspace/main.zena',
  target: 'host',
});
let checked = checkCompilation(result);

Compiling a File to WebAssembly#

Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:

import { compileFile } from 'compiler/compile-file';

let ok = await compileFile({
  entry: 'src/main.zena',
  outPath: 'out/main.wasm',
  stdlibRoot: '/stdlib',
});

Libraries#

  • compiler / compiler/compiler — compiler entry point (Compiler, createCompiler, checkCompilation, ProgramCheckResult)
  • compiler/compile-file — end-to-end file compilation (compileFile, CompileFileOptions)
  • compiler/tokenizer — lexer and token definitions (tokenize, Token, TokenType)
  • compiler/parser — recursive-descent parser (parse, Parser)
  • compiler/ast — AST node definitions (Node, Module, Statement, Expression, TypeAnnotation)
  • compiler/visitor — AST traversal helpers (walk, Visitor)
  • compiler/scope — lexical scope and symbol resolution (ScopeBuilder, ScopeResult, Symbol)
  • compiler/checker — static type checker (checkModule, CheckResult)
  • compiler/semantic-model — semantic queries over a checked module (SemanticModel)
  • compiler/types — compiler type representations (Type, ClassType, FunctionType, typeToString)
  • compiler/diagnostics — compiler diagnostics and source spans (Diagnostic, DiagnosticCode, DiagnosticSeverity, SourceSpan)
  • compiler/package-manifest — zena-package.json manifest and workspace loader (loadWorkspace, loadPackageMap)
  • compiler/module-resolver — package and relative module specifier resolution (ModuleResolver, PackageConfig)
  • compiler/library-loader — module graph loader (LibraryLoader, CompilerHost, SourceFile)
  • compiler/codegen/binary-generator — WebAssembly GC binary emitter (BinaryGenerator)
  • compiler/codegen/wat-generator — WebAssembly Text (WAT) emitter (WatGenerator)

License#

MIT

17.4 KiB Raw
import {
  ValType, ValTypeRef, ValTypeRefNull, valTypeToOpcode,
} from '../wasm.zena';
import { IrBody, IrBlock, IrOp, IrRef, isIrTerminator } from './ir.zena';
import { simdInstruction } from '../../simd.zena';
import { TemplateRecorder } from './template.zena';
import { growable } from 'zena:core';

/**
 * Compares ref targets by OBJECT IDENTITY, not type-section index:
 * indices are all -1 until layout() runs, so index equality spuriously
 * merges distinct types in bodies built pre-layout (the generator
 * split pass builds bodies there). Identity is equivalent to index
 * equality for laid-out types — see valTypeKeyEquals in
 * wasm-module.zena for the same reasoning.
 */
export function valTypesStrictlyEqual(a: ValType, b: ValType): boolean {
  return match (a) {
  case ValTypeRef as ta: match (b) {
    case ValTypeRef as tb: ta.target === tb.target
    case _: false
  }
  case ValTypeRefNull as ta: match (b) {
    case ValTypeRefNull as tb: ta.target === tb.target
    case _: false
  }
  case _: valTypeToOpcode(a) == valTypeToOpcode(b)
};
}

/**
 * ZIR construction API.
 *
 * The builder owns an IrBody under construction. Blocks are created with
 * newBlock(); instructions append to the current block (switchTo) until a
 * terminator is emitted, which closes the block. Types and refs are interned
 * into the body's tables.
 *
 * The builder enforces only local well-formedness (no emission into a
 * terminated or unselected block); global SSA invariants (dominance, branch
 * arity) are the verifier's job.
 */
export final class IrBuilder {
  body = new IrBody();
  var #current: i32 = -1;
  /**
   * Template mode (template.zena): every `internType` call appends a
   * type-table entry instead of interning, so two lowerings of one
   * method name their types by call order and their tables line up
   * entry for entry; the recorder collects lowering's guards. Null
   * otherwise.
   */
  var recorder: TemplateRecorder | null = null;
  /**
   * The result types of the function, while its returns are redirected
   * to one block (`redirectReturns`); null otherwise.
   */
  var #redirectedReturnTypes: GrowableArray<ValType> | null = null;
  /** The block redirected returns go to, or -1 until one is emitted. */
  var #redirectedReturnBlock: i32 = -1;

  /** Total blocks created so far. */
  numBlocks(): i32 {
    return this.body.blocks.length;
  }

  /**
   * Allocate a fresh block. It is not current until switchTo(b) is called.
   */
  newBlock(): i32 {
    let idx = this.body.blocks.length;
    this.body.blocks.push(new IrBlock());
    return idx;
  }

  /**
   * Select `block` as the insertion target for subsequent emissions. Fails if
   * `block` has already received a terminator instruction.
   */
  switchTo(block: i32): void {
    if (block < 0 || block >= this.body.blocks.length) {
      throw new Error('switchTo: no such block');
    }
    if (this.#isTerminated(block)) {
      throw new Error('switchTo: block already terminated');
    }
    this.#current = block;
  }

  /** Current insertion target (-1 before first switchTo). */
  currentBlock(): i32 {
    return this.#current;
  }

  /**
   * Adds a parameter to a block. Parameters may be added until the block
   * gains its terminator (on-demand params are how loop-carried values
   * appear during lowering).
   */
  blockParam(block: i32, type: ValType): i32 {
    if (this.#isTerminated(block)) {
      throw new Error('blockParam: block already terminated');
    }
    let blk = this.body.blocks[block];
    let inst = this.#newInst(IrOp.param, this.internType(type),
        blk.params.length, -1, block);
    blk.params.push(inst);
    return inst;
  }

  internType(type: ValType): i32 {
    let table = this.body.typeTable;
    if (this.recorder != null) {
      table.push(type);
      return table.length - 1;
    }
    var i = 0;
    while (i < table.length) {
      if (valTypesStrictlyEqual(table[i], type)) {
        return i;
      }
      i += 1;
    }
    table.push(type);
    return table.length - 1;
  }

  addRef(ref: IrRef): i32 {
    this.body.refTable.push(ref);
    return this.body.refTable.length - 1;
  }

  // -- Mutable variables (ir.md §5.1) ----------------------------------

  /** Allocates a fresh mutable variable of type `vt`; returns its id. */
  newVar(vt: ValType): i32 {
    this.body.varTypes.push(vt);
    return this.body.varTypes.length - 1;
  }

  /** Reads a mutable variable at its declared type. */
  varGet(varId: i32): i32 {
    return this.#emitInCurrent(IrOp.var_get,
        this.internType(this.body.varTypes[varId]), -1, varId);
  }

  /** Writes `value` into a mutable variable. */
  varSet(varId: i32, value: i32): void {
    this.#emitInCurrent(IrOp.var_set, -1, value, varId);
  }

  // -- Low-level emission ----------------------------------------------

  /** Emits a value-producing instruction with inline operands. */
  emit(op: IrOp, type: ValType, a: i32, b: i32): i32 {
    return this.#emitInCurrent(op, this.internType(type), a, b);
  }

  /** Emits a void instruction with inline operands. */
  emitVoid(op: IrOp, a: i32, b: i32): i32 {
    return this.#emitInCurrent(op, -1, a, b);
  }

  /** Copies `values` into the extra pool, returning the start index. */
  pushExtra(values: GrowableArray<i32>): i32 {
    let start = this.body.extra.length;
    for (let v in values) {
      this.body.extra.push(v);
    }
    return start;
  }

  /** Copies [argc, args...] into the extra pool. */
  pushArgList(args: GrowableArray<i32>): i32 {
    let start = this.body.extra.length;
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    return start;
  }

  // -- Typed helpers ------------------------------------------------------

  constI32(value: i32, type: ValType): i32 {
    return this.emit(IrOp.const_i32, type, value, -1);
  }

  constI64(value: i64, type: ValType): i32 {
    this.body.constI64.push(value);
    return this.emit(IrOp.const_i64, type, this.body.constI64.length - 1, -1);
  }

  constF64(value: f64, type: ValType): i32 {
    this.body.constF64.push(value);
    return this.emit(IrOp.const_f64, type, this.body.constF64.length - 1, -1);
  }

  /** f32 constants share the f64 pool (f32→f64 widening is exact). */
  constF32(value: f64, type: ValType): i32 {
    this.body.constF64.push(value);
    return this.emit(IrOp.const_f32, type, this.body.constF64.length - 1, -1);
  }

  /**
   * The all-zero vector. Wasm has no `v128` counterpart to `i32.const`
   * — the only vector constant is the 16-byte `v128.const` — so a zero
   * `v128` is an instruction with a sixteen-byte immediate rather than
   * a pooled literal.
   */
  constV128Zero(type: ValType): i32 {
    let instr = simdInstruction('v128.const');
    if (instr == null) {
      throw new Error('v128.const is missing from the SIMD table');
    }
    let imm = growable<i32>([instr.opcode]);
    var i = 0;
    while (i < 16) {
      imm.push(0);
      i += 1;
    }
    return this.emit(IrOp.simd_const, type, -1, this.pushExtra(imm));
  }

  binary(op: IrOp, type: ValType, x: i32, y: i32): i32 {
    return this.emit(op, type, x, y);
  }

  callFunc(funcRef: i32, args: GrowableArray<i32>, resultType: ValType | null): i32 {
    let argsIdx = this.pushArgList(args);
    if (resultType == null) {
      return this.#emitInCurrent(IrOp.call, -1, argsIdx, funcRef);
    }
    return this.#emitInCurrent(IrOp.call, this.internType(resultType),
        argsIdx, funcRef);
  }

  /**
   * Multi-result call: the call itself produces no single value; one
   * mv_get projection per result is emitted immediately after it, in
   * ascending result order (emission relies on that adjacency+order).
   */
  callFuncMulti(funcRef: i32, args: GrowableArray<i32>, resultTypes: GrowableArray<ValType>): GrowableArray<i32> {
    let argsIdx = this.pushArgList(args);
    let call = this.#emitInCurrent(IrOp.call, -1, argsIdx, funcRef);
    let projections = new Array<i32>(resultTypes.length);
    for (var k = 0; k < resultTypes.length; k += 1) {
      projections.push(this.#emitInCurrent(IrOp.mv_get,
          this.internType(resultTypes[k]), call, k));
    }
    return projections;
  }

  /**
   * A wide-arithmetic instruction: two i64 results, low half first,
   * read through mv_get projections under the same contract as a
   * multi-result call (emitted immediately after, ascending order).
   * `operands` is the pair for the multiplies and the
   * [lhsLo, lhsHi, rhsLo, rhsHi] quadruple for add128/sub128.
   */
  wideArith(op: IrOp, operands: GrowableArray<i32>, resultType: ValType): GrowableArray<i32> {
    let producer = if (operands.length == 2) {
      this.#emitInCurrent(op, -1, operands[0], operands[1])
    } else {
      this.#emitInCurrent(op, -1, this.pushExtra(operands), -1)
    };
    let projections = new Array<i32>(2);
    for (var k = 0; k < 2; k += 1) {
      projections.push(this.#emitInCurrent(IrOp.mv_get,
          this.internType(resultType), producer, k));
    }
    return projections;
  }

  /** Multi-value return. */
  retMulti(values: GrowableArray<i32>): void {
    if (this.#redirectedReturnTypes != null) {
      this.br(this.#returnTarget(), values);
      return;
    }
    let idx = this.body.extra.length;
    this.body.extra.push(values.length);
    for (let v in values) {
      this.body.extra.push(v);
    }
    this.#emitInCurrent(IrOp.ret_multi, -1, idx, -1);
  }

  /** array.new_data: bytes [offset, offset+length) of data segment
   * `dataIndex` as a fresh array of the given (byte) array type. */
  arrayNewData(offset: i32, length: i32, dataIndex: i32, typeRef: i32,
      resultType: ValType): i32 {
    let idx = this.body.extra.length;
    this.body.extra.push(offset);
    this.body.extra.push(length);
    this.body.extra.push(dataIndex);
    return this.#emitInCurrent(IrOp.array_new_data,
        this.internType(resultType), idx, typeRef);
  }

  /** Multi-result call_ref; same projection contract as callFuncMulti. */
  callRefMulti(callee: i32, args: GrowableArray<i32>, resultTypes: GrowableArray<ValType>): GrowableArray<i32> {
    let start = this.body.extra.length;
    this.body.extra.push(callee);
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    let call = this.#emitInCurrent(IrOp.call_ref, -1, start, -1);
    let projections = new Array<i32>(resultTypes.length);
    for (var k = 0; k < resultTypes.length; k += 1) {
      projections.push(this.#emitInCurrent(IrOp.mv_get,
          this.internType(resultTypes[k]), call, k));
    }
    return projections;
  }

  /** call_ref through a funcref value: extra = [callee, argc, arg*]. */
  callRef(callee: i32, args: GrowableArray<i32>, resultType: ValType | null): i32 {
    let start = this.body.extra.length;
    this.body.extra.push(callee);
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    if (resultType == null) {
      return this.#emitInCurrent(IrOp.call_ref, -1, start, -1);
    }
    return this.#emitInCurrent(IrOp.call_ref, this.internType(resultType),
        start, -1);
  }

  // -- Terminators ---------------------------------------------------------

  br(target: i32, args: GrowableArray<i32>): void {
    let idx = this.body.extra.length;
    this.body.extra.push(target);
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    this.#emitInCurrent(IrOp.br, -1, idx, -1);
  }

  brIf(cond: i32, thenTarget: i32, thenArgs: GrowableArray<i32>,
       elseTarget: i32, elseArgs: GrowableArray<i32>): void {
    let idx = this.body.extra.length;
    this.body.extra.push(thenTarget);
    this.body.extra.push(thenArgs.length);
    for (let v in thenArgs) {
      this.body.extra.push(v);
    }
    this.body.extra.push(elseTarget);
    this.body.extra.push(elseArgs.length);
    for (let v in elseArgs) {
      this.body.extra.push(v);
    }
    this.#emitInCurrent(IrOp.br_if, -1, cond, idx);
  }

  /** try_br: a = tag ref, b = [bodyTarget, argc, arg*, catchTarget,
   * argc, arg*]. Terminator; both edges carry block arguments.
   * Returns the instruction id so lowering can record the region's
   * join in `body.tryJoin` once it exists. */
  tryBr(tagRef: i32, bodyTarget: i32, bodyArgs: GrowableArray<i32>,
      catchTarget: i32, catchArgs: GrowableArray<i32>): i32 {
    let idx = this.body.extra.length;
    this.body.extra.push(bodyTarget);
    this.body.extra.push(bodyArgs.length);
    for (let v in bodyArgs) {
      this.body.extra.push(v);
    }
    this.body.extra.push(catchTarget);
    this.body.extra.push(catchArgs.length);
    for (let v in catchArgs) {
      this.body.extra.push(v);
    }
    return this.#emitInCurrent(IrOp.try_br, -1, tagRef, idx);
  }

  ret(value: i32): i32 {
    if (this.#redirectedReturnTypes != null) {
      this.br(this.#returnTarget(), growable<i32>([value]));
      return -1;
    }
    return this.#emitInCurrent(IrOp.ret, -1, value, -1);
  }

  /**
   * From here on, a return branches to one block that takes the
   * returned values as its parameters, of the function's result
   * `types`. A function with postconditions checks them there and then
   * returns (docs/design/contracts.md). The block is made by the first
   * return to reach it, so a function that never returns has none.
   */
  redirectReturns(types: GrowableArray<ValType>): void {
    this.#redirectedReturnTypes = types;
    this.#redirectedReturnBlock = -1;
  }

  /**
   * Stops redirecting returns. Answers the block they went to, or -1
   * when none was emitted.
   */
  endReturnRedirect(): i32 {
    this.#redirectedReturnTypes = null;
    return this.#redirectedReturnBlock;
  }

  #returnTarget(): i32 {
    if (this.#redirectedReturnBlock < 0) {
      let block = this.newBlock();
      for (let type in this.#redirectedReturnTypes as GrowableArray<ValType>) {
        this.blockParam(block, type);
      }
      this.#redirectedReturnBlock = block;
    }
    return this.#redirectedReturnBlock;
  }

  /**
   * `ret_call`: a tail call to a known function, encoded exactly as
   * `call` but terminating the block and producing no value — the
   * callee's results are this function's results
   * (docs/design/tail-calls.md). The caller owes the wasm rule that
   * the callee's results are subtypes of this function's.
   */
  retCall(funcRef: i32, args: GrowableArray<i32>): void {
    let argsIdx = this.pushArgList(args);
    this.#emitInCurrent(IrOp.ret_call, -1, argsIdx, funcRef);
  }

  /** `ret_call_ref`: the same, through a funcref. Encoded exactly as
   * `call_ref` — [callee, argc, arg*] — and terminating. */
  retCallRef(callee: i32, args: GrowableArray<i32>): void {
    let start = this.body.extra.length;
    this.body.extra.push(callee);
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    this.#emitInCurrent(IrOp.ret_call_ref, -1, start, -1);
  }

  /** yield_: a = yielded value, b = [resumeTarget, argc, arg*].
   * Suspension terminator for presplit generator bodies; the split
   * pass rewrites every yield before emission. */
  yieldTo(value: i32, resumeTarget: i32, args: GrowableArray<i32>): void {
    let idx = this.body.extra.length;
    this.body.extra.push(resumeTarget);
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    this.#emitInCurrent(IrOp.yield_, -1, value, idx);
  }

  /** await_: a = awaited future, b = [resumeTarget, argc, arg*].
   * Suspension terminator for presplit async bodies; the split pass
   * rewrites every await before emission. */
  awaitTo(future: i32, resumeTarget: i32, args: GrowableArray<i32>): i32 {
    let idx = this.body.extra.length;
    this.body.extra.push(resumeTarget);
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    return this.#emitInCurrent(IrOp.await_, -1, future, idx);
  }

  retVoid(): void {
    if (this.#redirectedReturnTypes != null) {
      this.br(this.#returnTarget(), new Array<i32>(0));
      return;
    }
    this.#emitInCurrent(IrOp.ret, -1, -1, -1);
  }

  unreachable(): void {
    this.#emitInCurrent(IrOp.unreachable, -1, -1, -1);
  }

  /** throw: extra = [argc, arg*], b = tag ref. Terminator. */
  throwWithTag(args: GrowableArray<i32>, tagRef: i32): void {
    let idx = this.body.extra.length;
    this.body.extra.push(args.length);
    for (let v in args) {
      this.body.extra.push(v);
    }
    this.#emitInCurrent(IrOp.throw, -1, idx, tagRef);
  }

  /**
   * Finishes construction and returns the body. Structural validity
   * (all blocks terminated, SSA invariants) is checked by the verifier,
   * not here, so tests can construct deliberately broken bodies.
   */
  finish(): IrBody {
    this.#current = -1;
    return this.body;
  }

  // -- Internals ------------------------------------------------------

  #isTerminated(block: i32): boolean {
    let insts = this.body.blocks[block].insts;
    if (insts.length == 0) {
      return false;
    }
    return isIrTerminator(this.body.op(insts[insts.length - 1]));
  }

  #newInst(op: IrOp, typeId: i32, a: i32, b: i32, block: i32): i32 {
    let {body} = this;
    body.opcode.push(op as i32);
    body.typeId.push(typeId);
    body.a.push(a);
    body.b.push(b);
    body.instBlock.push(block);
    return body.opcode.length - 1;
  }

  #emitInCurrent(op: IrOp, typeId: i32, a: i32, b: i32): i32 {
    if (this.#current < 0) {
      throw new Error('emit: no current block');
    }
    if (this.#isTerminated(this.#current)) {
      throw new Error('emit: current block already terminated');
    }
    let inst = this.#newInst(op, typeId, a, b, this.#current);
    this.body.blocks[this.#current].insts.push(inst);
    return inst;
  }
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19