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

13.8 KiB Raw
export enum SectionId {
  Type = 1,
  Import = 2,
  Function = 3,
  Table = 4,
  Memory = 5,
  Global = 6,
  Export = 7,
  Start = 8,
  Element = 9,
  Code = 10,
  Data = 11,
  DataCount = 12,
  Tag = 13
}

var _nextWasmTypeUid = 1;
export function nextWasmTypeUid(): i32 {
  let id = _nextWasmTypeUid;
  _nextWasmTypeUid += 1;
  return id;
}

/**
 * Restarts the uid sequence. `ModuleGenerator.compile` calls this so a
 * module's uids depend only on that module.
 *
 * These uids are `hashCode`, so they set the iteration order of every
 * HashMap and HashSet keyed by a WasmType or WasmFunction — and that
 * order reaches the output. Left running across compilations, a module
 * would be emitted differently depending on how many modules preceded
 * it in the process. Everything they key is built fresh by each module
 * pass (the WasmModule model and its types and functions), so nothing
 * from an earlier pass is alive to collide with the restarted sequence.
 */
export function resetWasmTypeUids(): void {
  _nextWasmTypeUid = 1;
}

export class WasmType implements Hashable {
  var index: i32 = -1;
  /** Process-unique id, used for identity-based cache keys. */
  uid: i32 = nextWasmTypeUid();

  /**
   * Identity hash. Without this, HashMap/HashSet keyed by WasmType fall back
   * to a constant hash and degenerate into linear scans.
   */
  hashCode(): i32 {
    return this.uid;
  }

  /** Identity equality, paired with the uid hash. */
  operator ==(other: WasmType): boolean {
    return this === other;
  }
}

export sealed class ValType {
  case ValTypeVoid
  case ValTypeFunc
  case ValTypeI32
  case ValTypeI64
  case ValTypeF32
  case ValTypeF64
  case ValTypeV128
  case ValTypeFuncRef
  case ValTypeExternRef
  case ValTypeRefExtern
  case ValTypeAnyRef
  case ValTypeEqRef
  case ValTypeStructRef
  /**
   * `nullref`, `(ref null none)`: the bottom of the `any` hierarchy,
   * whose only value is null. An inline-union lane every arm leaves as
   * a hole (`_`) lowers to it, so a two-arm `Step` forwards through a
   * three-lane `AsyncStep` slot — null is a subtype of every nullable
   * reference type.
   */
  case ValTypeNullRef
  case ValTypeOptRef
  case ValTypeRef(target: WasmType)
  case ValTypeRefNull(target: WasmType)
  case ValTypeI8
  case ValTypeI16
}

/**
 * What an import brings in: its external type in the import section. Two
 * that are equal encode the same bytes, which is what lets imports share
 * one (import-plan.zena).
 */
export sealed class ImportDesc implements Hashable {
  operator ==(other: ImportDesc): boolean {
    return match (this) {
      case FuncImport {typeIndex}: match (other) {
        case FuncImport {typeIndex as otherIndex}: typeIndex == otherIndex
        case _: false
      }
      case GlobalImport {type, isMutable}: match (other) {
        case GlobalImport {type as otherType, isMutable as otherMutable}:
            isMutable == otherMutable && sameValTypeBytes(type, otherType)
        case _: false
      }
      case MemoryImport {minPages}: match (other) {
        case MemoryImport {minPages as otherPages}: minPages == otherPages
        case _: false
      }
    };
  }

  hashCode(): i32 {
    return match (this) {
      case FuncImport {typeIndex}: typeIndex * 31 + 1
      case GlobalImport {type, isMutable}:
          (valTypeToOpcode(type) * 31 + refTargetIndex(type)) * 31 + (if (isMutable) 3 else 2)
      case MemoryImport {minPages}: minPages * 31 + 4
    };
  }

  case FuncImport(typeIndex: i32)
  case GlobalImport(type: ValType, isMutable: boolean)
  case MemoryImport(minPages: i32)
}

/** Whether `emitValType` writes the same bytes for both: one opcode, and one heap type for a ref. */
function sameValTypeBytes(a: ValType, b: ValType): boolean {
  if (valTypeToOpcode(a) != valTypeToOpcode(b)) {
    return false;
  }
  return match (a) {
    case ValTypeRef {target}: target == (b as ValTypeRef).target
    case ValTypeRefNull {target}: target == (b as ValTypeRefNull).target
    case _: true
  };
}

function refTargetIndex(type: ValType): i32 {
  return match (type) {
    case ValTypeRef {target}: target.index
    case ValTypeRefNull {target}: target.index
    case _: 0
  };
}

export function valTypeToOpcode(type: ValType): i32 {
  return match (type) {
  case ValTypeVoid: 0x40
  case ValTypeFunc: 0x60
  case ValTypeI32: 0x7F
  case ValTypeI64: 0x7E
  case ValTypeF32: 0x7D
  case ValTypeF64: 0x7C
  case ValTypeV128: 0x7B
  case ValTypeFuncRef: 0x70
  case ValTypeExternRef: 0x6F
  case ValTypeRefExtern: 0x65
  case ValTypeAnyRef: 0x6E
  case ValTypeEqRef: 0x6D
  case ValTypeStructRef: 0x6B
  case ValTypeNullRef: 0x71
  case ValTypeOptRef: 0x6C
  case ValTypeRef: 0x64
  case ValTypeRefNull: 0x63
  case ValTypeI8: 0x78
  case ValTypeI16: 0x77
};
}

/**
 * Whether two ref valtypes name the same heap type.
 *
 * Identity first: the type pools dedupe at construction, so one heap
 * type is one object, and layout() gives every object its own index —
 * identity and index equality agree once indices exist. Before
 * layout() every index is still -1, and an index-only comparison made
 * every ref type equal every other. The split passes (ir/async.zena,
 * ir/generators.zena) lower whole bodies before layout(), where that
 * false equality silently skipped narrowing casts: `x is Sub` in an
 * async body read members off the DECLARED class and failed with
 * "member not found". The index half stays for laid-out types, where
 * it is the emitted meaning of "same type".
 */
export function sameHeapType(a: WasmType, b: WasmType): boolean {
  return a == b || (a.index != -1 && a.index == b.index);
}

export function valTypeEquals(a: ValType, b: ValType): boolean {
  return match (a) {
    case ValTypeRef as ta: match (b) {
      case ValTypeRef as tb: sameHeapType(ta.target, tb.target)
      case ValTypeRefNull as tb: sameHeapType(ta.target, tb.target)
      case _: false
    }
    case ValTypeRefNull as ta: match (b) {
      case ValTypeRef as tb: sameHeapType(ta.target, tb.target)
      case ValTypeRefNull as tb: sameHeapType(ta.target, tb.target)
      case _: false
    }
    case ValTypeRefExtern: match (b) {
      case ValTypeRefExtern: true
      case ValTypeExternRef: true
      case _: false
    }
    case ValTypeExternRef: match (b) {
      case ValTypeRefExtern: true
      case ValTypeExternRef: true
      case _: false
    }
    case _: valTypeToOpcode(a) == valTypeToOpcode(b)
  };
}

export function isWasmSubtype(sub: ValType, superType: ValType): boolean {
  return match (sub) {
  case ValTypeRef as ta: match (superType) {
    case ValTypeRef as tb: sameHeapType(ta.target, tb.target)
    case ValTypeRefNull as tb: sameHeapType(ta.target, tb.target)
    case ValTypeEqRef: true
    case ValTypeStructRef: true
    case ValTypeAnyRef: true
    case _: false
  }
  case ValTypeRefNull as ta: match (superType) {
    case ValTypeRefNull as tb: sameHeapType(ta.target, tb.target)
    case ValTypeEqRef: true
    case ValTypeStructRef: true
    case ValTypeAnyRef: true
    case _: false
  }
  case ValTypeNullRef: isNullableAnyRef(superType)
  case ValTypeRefExtern: match (superType) {
    case ValTypeRefExtern: true
    case ValTypeExternRef: true
    case _: false
  }
  case ValTypeExternRef: superType is ValTypeExternRef
  case _: valTypeToOpcode(sub) == valTypeToOpcode(superType)
};
}

/** A reference type in the `any` hierarchy that admits null. */
export function isNullableAnyRef(vt: ValType): boolean {
  return match (vt) {
    case ValTypeRefNull: true
    case ValTypeAnyRef: true
    case ValTypeEqRef: true
    case ValTypeStructRef: true
    case ValTypeNullRef: true
    case _: false
  };
}

/**
 * The WasmType behind a concrete reference ValType — nullable or
 * not — or null for scalars and abstract heap types.
 */
export function refTargetOf(vt: ValType): WasmType | null {
  return match (vt) {
    case ValTypeRef as r: r.target
    case ValTypeRefNull as rn: rn.target
    case _: null
  };
}

/** A reference in the `extern` hierarchy, nullable or not. */
export function isExternValType(vt: ValType): boolean {
  return vt is ValTypeExternRef || vt is ValTypeRefExtern;
}

/** Any reference-typed ValType, concrete or abstract heap type. */
export function isRefValType(vt: ValType): boolean {
  return match (vt) {
    case ValTypeRef: true
    case ValTypeRefNull: true
    case ValTypeAnyRef: true
    case ValTypeEqRef: true
    case ValTypeStructRef: true
    case ValTypeFuncRef: true
    case ValTypeExternRef: true
    case ValTypeNullRef: true
    case ValTypeRefExtern: true
    case _: false
  };
}

export enum HeapType {
  func = 0x70,
  extern = 0x6F,
  any = 0x6E,
  eq = 0x6D,
  struct = 0x6B,
  array = 0x6A,
  i31 = 0x6C,
  none = 0x71,
  noextern = 0x72,
  nofunc = 0x73,
}

export function heapTypeToSigned(type: HeapType): i32 {
  return (type as i32) - 128;
}

export enum GcOpcode {
  struct_new = 0x00,
  struct_new_default = 0x01,
  struct_get = 0x02,
  struct_get_s = 0x03,
  struct_get_u = 0x04,
  struct_set = 0x05,
  array_new = 0x06,
  array_new_default = 0x07,
  array_new_fixed = 0x08,
  array_new_data = 0x09,
  array_new_elem = 0x0A,
  array_get = 0x0B,
  array_get_s = 0x0C,
  array_get_u = 0x0D,
  array_set = 0x0E,
  array_len = 0x0F,
  array_copy = 0x11,
  extern_convert_any = 0x1B,
  any_convert_extern = 0x1A,
  ref_test = 0x14,
  ref_test_null = 0x15,
  ref_cast = 0x16,
  ref_cast_null = 0x17,
  ref_i31 = 0x1C,
  i31_get_s = 0x1D,
  i31_get_u = 0x1E,
}

export enum Opcode {
  unreachable = 0x00,
  block = 0x02,
  loop = 0x03,
  if_ = 0x04,
  else_ = 0x05,
  end = 0x0B,
  br = 0x0C,
  br_if = 0x0D,
  return_ = 0x0F,
  call = 0x10,
  return_call = 0x12,
  local_get = 0x20,
  local_set = 0x21,
  local_tee = 0x22,
  global_get = 0x23,
  global_set = 0x24,
  i32_load = 0x28,
  i32_load8_u = 0x2D,
  i32_store = 0x36,
  i32_store8 = 0x3A,
  i64_load = 0x29,
  i64_store = 0x37,
  f32_load = 0x2A,
  f32_store = 0x38,
  f64_load = 0x2B,
  f64_store = 0x39,
  memory_size = 0x3F,
  memory_grow = 0x40,
  drop = 0x1A,
  gc_prefix = 0xFB,
  sat_prefix = 0xFC,
  /** Vector instructions: this byte then a ULEB128 opcode. */
  simd_prefix = 0xFD,
  i32_const = 0x41,
  i64_const = 0x42,
  i32_eqz = 0x45,
  i32_eq = 0x46,
  i32_ne = 0x47,
  i32_lt_s = 0x48,
  i32_lt_u = 0x49,
  i32_gt_s = 0x4A,
  i32_gt_u = 0x4B,
  i32_le_s = 0x4C,
  i32_le_u = 0x4D,
  i32_ge_s = 0x4E,
  i32_ge_u = 0x4F,
  i32_clz = 0x67,
  i32_ctz = 0x68,
  i32_popcnt = 0x69,
  i32_add = 0x6A,
  i32_sub = 0x6B,
  i32_mul = 0x6C,
  i32_div_s = 0x6D,
  i32_div_u = 0x6E,
  i32_rem_s = 0x6F,
  i32_rem_u = 0x70,
  i32_and = 0x71,
  i32_or = 0x72,
  i32_xor = 0x73,
  i32_shl = 0x74,
  i32_shr_s = 0x75,
  i32_shr_u = 0x76,
  i64_eqz = 0x50,
  i64_eq = 0x51,
  i64_ne = 0x52,
  i64_lt_s = 0x53,
  i64_lt_u = 0x54,
  i64_gt_s = 0x55,
  i64_gt_u = 0x56,
  i64_le_s = 0x57,
  i64_le_u = 0x58,
  i64_ge_s = 0x59,
  i64_ge_u = 0x5A,
  i64_clz = 0x79,
  i64_ctz = 0x7A,
  i64_popcnt = 0x7B,
  i64_add = 0x7C,
  i64_sub = 0x7D,
  i64_mul = 0x7E,
  i64_div_s = 0x7F,
  i64_div_u = 0x80,
  i64_rem_s = 0x81,
  i64_rem_u = 0x82,
  i64_and = 0x83,
  i64_or = 0x84,
  i64_xor = 0x85,
  i64_shl = 0x86,
  i64_shr_s = 0x87,
  i64_shr_u = 0x88,
  f32_const = 0x43,
  f32_eq = 0x5B,
  f32_ne = 0x5C,
  f32_lt = 0x5D,
  f32_gt = 0x5E,
  f32_le = 0x5F,
  f32_ge = 0x60,
  f32_abs = 0x8B,
  f32_neg = 0x8C,
  f32_ceil = 0x8D,
  f32_floor = 0x8E,
  f32_trunc = 0x8F,
  f32_nearest = 0x90,
  f32_sqrt = 0x91,
  f32_add = 0x92,
  f32_sub = 0x93,
  f32_mul = 0x94,
  f32_div = 0x95,
  f32_min = 0x96,
  f32_max = 0x97,
  f32_copysign = 0x98,
  f32_convert_i32_s = 0xB2,
  f32_convert_i32_u = 0xB3,
  f32_convert_i64_s = 0xB4,
  f32_convert_i64_u = 0xB5,
  f32_demote_f64 = 0xB6,
  f64_const = 0x44,
  f64_eq = 0x61,
  f64_ne = 0x62,
  f64_lt = 0x63,
  f64_gt = 0x64,
  f64_le = 0x65,
  f64_ge = 0x66,
  f64_abs = 0x99,
  f64_neg = 0x9A,
  f64_ceil = 0x9B,
  f64_floor = 0x9C,
  f64_trunc = 0x9D,
  f64_nearest = 0x9E,
  f64_sqrt = 0x9F,
  f64_add = 0xA0,
  f64_sub = 0xA1,
  f64_mul = 0xA2,
  f64_div = 0xA3,
  f64_min = 0xA4,
  f64_max = 0xA5,
  f64_copysign = 0xA6,
  f64_convert_i32_s = 0xB7,
  f64_convert_i32_u = 0xB8,
  f64_convert_i64_s = 0xB9,
  f64_convert_i64_u = 0xBA,
  f64_promote_f32 = 0xBB,
  i32_wrap_i64 = 0xA7,
  i64_extend_i32_s = 0xAC,
  i64_extend_i32_u = 0xAD,
  i32_reinterpret_f32 = 0xBC,
  i64_reinterpret_f64 = 0xBD,
  f32_reinterpret_i32 = 0xBE,
  f64_reinterpret_i64 = 0xBF,
  ref_null = 0xD0,
  ref_is_null = 0xD1,
  ref_func = 0xD2,
  ref_eq = 0xD3,
  ref_as_non_null = 0xD4,
  call_ref = 0x14,
  return_call_ref = 0x15,
  throw = 0x08,
  try_table = 0x1F
}

export enum SatOpcode {
  i32_trunc_sat_f32_s = 0x00,
  i32_trunc_sat_f32_u = 0x01,
  i32_trunc_sat_f64_s = 0x02,
  i32_trunc_sat_f64_u = 0x03,
  i64_trunc_sat_f32_s = 0x04,
  i64_trunc_sat_f32_u = 0x05,
  i64_trunc_sat_f64_s = 0x06,
  i64_trunc_sat_f64_u = 0x07
}

/**
 * The wide-arithmetic proposal, which shares `sat_prefix` (0xFC) with
 * the saturating truncations — 0..7 are those, 8..17 are bulk-memory
 * and reference-types, 18 is the proposed `memory.discard`, and these
 * four sit above it. Values are the proposal's, in DECIMAL, and are
 * written as a ULEB128 u32 after the prefix byte.
 */
export enum WideArithOpcode {
  i64_add128 = 19,
  i64_sub128 = 20,
  i64_mul_wide_s = 21,
  i64_mul_wide_u = 22
}

/** The text-format mnemonic for a wide-arithmetic opcode. */
export function wideArithName(opcode: i32): String {
  if (opcode == WideArithOpcode.i64_add128 as i32) { return 'i64.add128'; }
  if (opcode == WideArithOpcode.i64_sub128 as i32) { return 'i64.sub128'; }
  if (opcode == WideArithOpcode.i64_mul_wide_s as i32) { return 'i64.mul_wide_s'; }
  if (opcode == WideArithOpcode.i64_mul_wide_u as i32) { return 'i64.mul_wide_u'; }
  throw new Error('not a wide-arithmetic opcode: ' + i32ToString(opcode));
}

// TODO: Return typed references instead of anyref for references. To do this
// we need to change ValType from a simple enum to a sealed class with
// parameters for references types, so we can have something like
// ValType.Ref(structTypeIndex) or ValType.Array(elementTypeIndex).



VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19