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

21.2 KiB Raw
// AST Visitor Infrastructure
//
// Provides tree traversal utilities for compiler passes. Uses Zena's sealed
// class hierarchy + exhaustive match instead of the TypeScript-style visitor
// interface pattern.
//
// Three entry points:
//   walk(node, enter, leave)  — full pre+post-order traversal
//   walkEnter(node, fn)       — pre-order only (convenience)
//   walkChildren(node, enter, leave) — traverse children without visiting root


import {
  Node, Module,
  // Expressions
  Expression, Identifier, NumberLiteral, StringLiteral, BooleanLiteral,
  NullLiteral, TemplateLiteral, TaggedTemplateExpression, BinaryExpression,
  UnaryExpression, AssignmentExpression, AsExpression, IsExpression,
  RangeExpression, PipelineExpression, PipePlaceholder, FunctionExpression,
  CallExpression, MemberExpression, IndexExpression, ThisExpression,
  SuperExpression, NewExpression, ArrayLiteral, RecordLiteral, MapLiteral,
  TupleLiteral, MatchExpression, IfExpression, ThrowExpression, TryExpression, AwaitExpression, ShieldedStatement,
  // Statements
  Statement, VariableDeclaration, UsingStatement, FunctionDeclaration, ExpressionStatement, BlockStatement,
  ReturnStatement, YieldStatement, BreakStatement, ContinueStatement, IfStatement,
  WhileStatement, ForStatement, ForInStatement, ClassDeclaration,
  InterfaceDeclaration, EnumDeclaration, MixinDeclaration, TypeAliasDeclaration,
  ImportDeclaration, ExportAllDeclaration, ExportFromDeclaration, DeclareFunction, SymbolDeclaration,
  // Patterns
  Pattern, BindingPattern, IdentifierPattern, RecordPattern, TuplePattern, ArrayPattern, RestPattern, AsPattern,
  ClassPattern, LogicalPattern, AssignmentPattern, AbsencePattern, LiteralPattern,
  // Type Annotations
  TypeAnnotation, NamedTypeAnnotation, UnionTypeAnnotation, NullableTypeAnnotation,
  FunctionTypeAnnotation, LiteralTypeAnnotation, RecordTypeAnnotation,
  TupleTypeAnnotation, InlineTypeAnnotation, ThisTypeAnnotation,
  // Direct Node variants
  TemplateElement, PropertyAssignment, SpreadElement, MapEntry,
  BindingProperty, MatchCase, LetPatternCondition, TypeParameter, Parameter,
  CaseClassParam, SealedVariant, FieldDefinition, MethodDefinition,
  AccessorDeclaration, SetterInfo, FieldInitializer, SuperInitializer,
  MethodSignature, AccessorSignature, EnumMember, CatchClause,
  PropertySignature, ImportSpecifier, Decorator, ContractClause,
  SymbolPropertyName
} from './ast.zena';


// ============================================================================
// walkChildren — exhaustive match over every Node variant
// ============================================================================

/// Visit all children of a node without visiting the node itself.
export function walkChildren(node: Node, enter: (n: Node) => boolean, leave: (n: Node) => void): void {
  if (node is Expression) {
    match (node) {
      // -- Literals & Leaves (no children) --
      case Identifier {}: {}
      case NumberLiteral {}: {}
      case StringLiteral {}: {}
      case BooleanLiteral {}: {}
      case NullLiteral {}: {}
      case ThisExpression {}: {}
      case SuperExpression {}: {}
      case PipePlaceholder {}: {}

      // -- Templates --
      case TemplateLiteral {quasis, expressions}: {
        for (let q in quasis) { walk(q, enter, leave); }
        for (let e in expressions) { walk(e, enter, leave); }
      }
      case TaggedTemplateExpression {tag, quasi}: {
        walk(tag, enter, leave);
        walk(quasi, enter, leave);
      }

      // -- Operators --
      case BinaryExpression {left, right}: {
        walk(left, enter, leave);
        walk(right, enter, leave);
      }
      case UnaryExpression {argument}: {
        walk(argument, enter, leave);
      }
      case AssignmentExpression {left, value}: {
        walk(left, enter, leave);
        walk(value, enter, leave);
      }
      case AsExpression {expression, typeAnnotation}: {
        walk(expression, enter, leave);
        walk(typeAnnotation, enter, leave);
      }
      case IsExpression {expression, typeAnnotation}: {
        walk(expression, enter, leave);
        walk(typeAnnotation, enter, leave);
      }
      case RangeExpression {start, end}: {
        if (start != null) { walk(start, enter, leave); }
        if (end != null) { walk(end, enter, leave); }
      }
      case PipelineExpression {left, right}: {
        walk(left, enter, leave);
        walk(right, enter, leave);
      }

      // -- Functions & Calls --
      case FunctionExpression {typeParameters, params, returnType, body, contracts}: {
        if (typeParameters != null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        for (let p in params) { walk(p, enter, leave); }
        if (returnType != null) { walk(returnType, enter, leave); }
        if (contracts != null) { for (let c in contracts) { walk(c, enter, leave); } }
        walk(body, enter, leave);
      }
      case CallExpression {callee, args, typeArguments}: {
        walk(callee, enter, leave);
        for (let a in args) { walk(a, enter, leave); }
        if (typeArguments != null) { for (let t in typeArguments) { walk(t, enter, leave); } }
      }

      // -- Member Access --
      case MemberExpression {object, symbolPath}: {
        walk(object, enter, leave);
        // A symbol key is a real subtree — the `sym` of `x.:sym`, or the
        // `Iface.sym` of `x.:Iface.sym` — and nothing walked it. So
        // `assignNodeIds` never reached those nodes and they all kept the
        // default id, which collapsed every symbol path in a module onto
        // one entry of any node-keyed map: the reference map answered
        // every `x.:sym` with whichever symbol was recorded last.
        // (`property` stays unwalked, as for an ordinary member access;
        // for the unqualified form it IS this node.)
        if (symbolPath != null) {
          walk(symbolPath as Node, enter, leave);
        }
      }
      case IndexExpression {object, index}: {
        walk(object, enter, leave);
        walk(index, enter, leave);
      }
      case NewExpression {callee, typeArguments, args, constructorName}: {
        walk(callee, enter, leave);
        if (typeArguments != null) { for (let t in typeArguments) { walk(t, enter, leave); } }
        if (constructorName != null) { walk(constructorName as Node, enter, leave); }
        for (let a in args) { walk(a, enter, leave); }
      }

      // -- Collection Literals --
      case ArrayLiteral {elements}: {
        for (let e in elements) { walk(e, enter, leave); }
      }
      case RecordLiteral {properties}: {
        for (let p in properties) { walk(p, enter, leave); }
      }
      case MapLiteral {entries}: {
        for (let e in entries) { walk(e, enter, leave); }
      }
      case TupleLiteral {elements}: {
        for (let e in elements) { walk(e, enter, leave); }
      }

      // -- Control Flow Expressions --
      case MatchExpression {discriminant, cases}: {
        walk(discriminant, enter, leave);
        for (let c in cases) { walk(c, enter, leave); }
      }
      case IfExpression {test, consequent, alternate}: {
        walk(test, enter, leave);
        walk(consequent, enter, leave);
        if (alternate != null) { walk(alternate, enter, leave); }
      }

      // -- Error Handling Expressions --
      case ThrowExpression {argument}: {
        walk(argument, enter, leave);
      }
      case AwaitExpression {argument}: {
        walk(argument, enter, leave);
      }
      case TryExpression {body, handler, cancelBlock, finalizer}: {
        walk(body, enter, leave);
        if (handler != null) { walk(handler, enter, leave); }
        if (cancelBlock != null) { walk(cancelBlock, enter, leave); }
        if (finalizer != null) { walk(finalizer, enter, leave); }
      }
    }
  } else if (node is Statement) {
    match (node) {
      case VariableDeclaration {pattern, typeAnnotation, init}: {
        walk(pattern, enter, leave);
        if (typeAnnotation != null) { walk(typeAnnotation, enter, leave); }
        walk(init, enter, leave);
      }
      case ShieldedStatement {body}: {
        walk(body, enter, leave);
      }
      case UsingStatement {pattern, typeAnnotation, init}: {
        if (pattern != null) { walk(pattern, enter, leave); }
        if (typeAnnotation != null) { walk(typeAnnotation, enter, leave); }
        walk(init, enter, leave);
      }
      case FunctionDeclaration {name, func}: {
        walk(name, enter, leave);
        walk(func, enter, leave);
      }
      case ExpressionStatement {expression}: {
        walk(expression, enter, leave);
      }
      case BlockStatement {body}: {
        for (let stmt in body) { walk(stmt, enter, leave); }
      }
      case ReturnStatement {argument}: {
        if (argument != null) { walk(argument, enter, leave); }
      }
      case YieldStatement {argument}: {
        walk(argument, enter, leave);
      }
      case BreakStatement {}: {}
      case ContinueStatement {}: {}
      case IfStatement {test, consequent, alternate}: {
        walk(test, enter, leave);
        walk(consequent, enter, leave);
        if (alternate != null) { walk(alternate, enter, leave); }
      }
      case WhileStatement {test, body, invariants}: {
        walk(test, enter, leave);
        if (invariants != null) { for (let c in invariants) { walk(c, enter, leave); } }
        walk(body, enter, leave);
      }
      case ForStatement {init, test, update, body, invariants}: {
        if (init != null) { walk(init, enter, leave); }
        if (test != null) { walk(test, enter, leave); }
        if (update != null) { walk(update, enter, leave); }
        if (invariants != null) { for (let c in invariants) { walk(c, enter, leave); } }
        walk(body, enter, leave);
      }
      case ForInStatement {pattern, iterable, body, invariants}: {
        walk(pattern, enter, leave);
        walk(iterable, enter, leave);
        if (invariants != null) { for (let c in invariants) { walk(c, enter, leave); } }
        walk(body, enter, leave);
      }
      case ClassDeclaration {name, typeParameters, caseParams, superClass, mixins, implementsList, body, sealedVariants, onType}: {
        walk(name, enter, leave);
        if (typeParameters != null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        if (caseParams != null) { for (let p in caseParams) { walk(p, enter, leave); } }
        if (superClass != null) { walk(superClass, enter, leave); }
        if (mixins != null) { for (let m in mixins) { walk(m, enter, leave); } }
        if (implementsList != null) { for (let i in implementsList) { walk(i, enter, leave); } }
        for (let member in body) { walk(member, enter, leave); }
        if (sealedVariants != null) { for (let v in sealedVariants) { walk(v, enter, leave); } }
        if (onType != null) { walk(onType, enter, leave); }
      }
      case InterfaceDeclaration {name, typeParameters, extendsList, body}: {
        walk(name, enter, leave);
        if (typeParameters != null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        if (extendsList != null) { for (let e in extendsList) { walk(e, enter, leave); } }
        for (let member in body) { walk(member, enter, leave); }
      }
      case EnumDeclaration {name, members}: {
        walk(name, enter, leave);
        for (let m in members) { walk(m, enter, leave); }
      }
      case MixinDeclaration {name, typeParameters, on, mixins, body, decoratorSubject}: {
        walk(name, enter, leave);
        if (typeParameters != null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        if (decoratorSubject != null) { walk(decoratorSubject, enter, leave); }
        if (on != null) { walk(on, enter, leave); }
        if (mixins != null) { for (let m in mixins) { walk(m, enter, leave); } }
        for (let member in body) { walk(member, enter, leave); }
      }
      case TypeAliasDeclaration {name, typeParameters, typeAnnotation, decorators}: {
        walk(name, enter, leave);
        if (typeParameters != null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        if (typeAnnotation != null) { walk(typeAnnotation, enter, leave); }
        for (let d in decorators) { walk(d, enter, leave); }
      }
      case ImportDeclaration {moduleSpecifier, imports}: {
        walk(moduleSpecifier, enter, leave);
        for (let spec in imports) { walk(spec, enter, leave); }
      }
      case ExportAllDeclaration {moduleSpecifier}: {
        walk(moduleSpecifier, enter, leave);
      }
      case ExportFromDeclaration {specifiers, moduleSpecifier}: {
        for (let spec in specifiers) { walk(spec, enter, leave); }
        walk(moduleSpecifier, enter, leave);
      }
      case DeclareFunction {name, typeParameters, params, returnType, decorators}: {
        walk(name, enter, leave);
        if (typeParameters != null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        for (let p in params) { walk(p, enter, leave); }
        walk(returnType, enter, leave);
        for (let d in decorators) { walk(d, enter, leave); }
      }
      case SymbolDeclaration {name}: {
        walk(name, enter, leave);
      }
    }
  } else if (node is Pattern) {
    match (node) {
      case BindingPattern as bp: { walk(bp.pattern, enter, leave); }
      case IdentifierPattern {}: {}  // leaf
      case RecordPattern {properties, rest}: {
        for (let p in properties) { walk(p, enter, leave); }
        if (rest !== null) { walk(rest, enter, leave); }
      }
      case TuplePattern {elements}: {
        for (let e in elements) { if (e !== null) { walk(e, enter, leave); } }
      }
      case ArrayPattern {elements}: {
        for (let e in elements) { if (e !== null) { walk(e, enter, leave); } }
      }
      case RestPattern {pattern}: {
        walk(pattern, enter, leave);
      }
      case AsPattern {pattern, name}: {
        walk(pattern, enter, leave);
        walk(name, enter, leave);
      }
      case ClassPattern {name, typeArguments, properties}: {
        walk(name, enter, leave);
        if (typeArguments !== null) { for (let t in typeArguments) { walk(t, enter, leave); } }
        for (let p in properties) { walk(p, enter, leave); }
      }
      case LogicalPattern {left, right}: {
        walk(left, enter, leave);
        walk(right, enter, leave);
      }
      case AssignmentPattern {left, right}: {
        walk(left, enter, leave);
        walk(right, enter, leave);
      }
      case LiteralPattern {value}: {
        walk(value, enter, leave);
      }
      case AbsencePattern {}: {}
    }
  } else if (node is TypeAnnotation) {
    match (node) {
      case NamedTypeAnnotation {typeArguments}: {
        if (typeArguments !== null) { for (let t in typeArguments) { walk(t, enter, leave); } }
      }
      case UnionTypeAnnotation {types}: {
        for (let t in types) { walk(t, enter, leave); }
      }
      case NullableTypeAnnotation {typeAnnotation}: {
        walk(typeAnnotation, enter, leave);
      }
      case FunctionTypeAnnotation {params, returnType}: {
        for (let p in params) { walk(p, enter, leave); }
        walk(returnType, enter, leave);
      }
      case LiteralTypeAnnotation {value}: {
        walk(value, enter, leave);
      }
      case RecordTypeAnnotation {properties, spreads}: {
        for (let p in properties) { walk(p, enter, leave); }
        if (spreads != null) {
          for (let s in spreads) { walk(s, enter, leave); }
        }
      }
      case TupleTypeAnnotation {elementTypes}: {
        for (let t in elementTypes) { walk(t, enter, leave); }
      }
      case InlineTypeAnnotation {typeAnnotation}: {
        walk(typeAnnotation, enter, leave);
      }
      case ThisTypeAnnotation {}: {}  // leaf
    }
  } else {
    match (node) {
      case Module {body}: {
        for (let stmt in body) { walk(stmt, enter, leave); }
      }
      case TemplateElement {}: {}  // leaf
      case PropertyAssignment {name, value}: {
        walk(name, enter, leave);
        walk(value, enter, leave);
      }
      case SpreadElement {argument}: {
        walk(argument, enter, leave);
      }
      case MapEntry {key, value}: {
        walk(key, enter, leave);
        walk(value, enter, leave);
      }
      case BindingProperty {name, value}: {
        walk(name, enter, leave);
        walk(value, enter, leave);
      }
      case MatchCase {pattern, guard, body}: {
        walk(pattern, enter, leave);
        if (guard !== null) { walk(guard, enter, leave); }
        walk(body, enter, leave);
      }
      case LetPatternCondition {pattern, init}: {
        walk(pattern, enter, leave);
        walk(init, enter, leave);
      }
      case TypeParameter {constraint, defaultType}: {
        if (constraint !== null) { walk(constraint, enter, leave); }
        if (defaultType !== null) { walk(defaultType, enter, leave); }
      }
      case Parameter {name, pattern, typeAnnotation, defaultValue}: {
        walk(name, enter, leave);
        if (pattern !== null) { walk(pattern, enter, leave); }
        if (typeAnnotation !== null) { walk(typeAnnotation, enter, leave); }
        if (defaultValue !== null) { walk(defaultValue, enter, leave); }
      }
      case CaseClassParam {name, typeAnnotation, defaultValue}: {
        walk(name, enter, leave);
        walk(typeAnnotation, enter, leave);
        if (defaultValue !== null) { walk(defaultValue, enter, leave); }
      }
      case SealedVariant {name, params}: {
        walk(name, enter, leave);
        if (params !== null) { for (let p in params) { walk(p, enter, leave); } }
      }
      case FieldDefinition {name, typeAnnotation, value}: {
        walk(name, enter, leave);
        if (typeAnnotation !== null) { walk(typeAnnotation, enter, leave); }
        if (value !== null) { walk(value, enter, leave); }
      }
      case MethodDefinition {name, typeParameters, receiver, params, returnType, body, initializerList, superInitializer, contracts}: {
        walk(name, enter, leave);
        if (typeParameters !== null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        if (receiver !== null) { walk(receiver as Node, enter, leave); }
        for (let p in params) { walk(p, enter, leave); }
        if (returnType !== null) { walk(returnType, enter, leave); }
        if (contracts !== null) { for (let c in contracts) { walk(c, enter, leave); } }
        if (body !== null) { walk(body, enter, leave); }
        if (initializerList !== null) { for (let i in initializerList) { walk(i, enter, leave); } }
        if (superInitializer !== null) { walk(superInitializer, enter, leave); }
      }
      case AccessorDeclaration {name, typeAnnotation, getter, setter}: {
        walk(name, enter, leave);
        walk(typeAnnotation, enter, leave);
        if (getter !== null) { walk(getter, enter, leave); }
        if (setter !== null) { walk(setter, enter, leave); }
      }
      case SetterInfo {param, body}: {
        walk(param, enter, leave);
        walk(body, enter, leave);
      }
      case FieldInitializer {field, value}: {
        walk(field, enter, leave);
        walk(value, enter, leave);
      }
      case SuperInitializer {args, constructorName}: {
        if (constructorName != null) { walk(constructorName as Node, enter, leave); }
        for (let a in args) { walk(a, enter, leave); }
      }
      case MethodSignature {name, typeParameters, params, returnType, contracts}: {
        walk(name, enter, leave);
        if (typeParameters !== null) { for (let t in typeParameters) { walk(t, enter, leave); } }
        for (let p in params) { walk(p, enter, leave); }
        if (returnType !== null) { walk(returnType, enter, leave); }
        if (contracts !== null) { for (let c in contracts) { walk(c, enter, leave); } }
      }
      case AccessorSignature {name, typeAnnotation}: {
        walk(name, enter, leave);
        walk(typeAnnotation, enter, leave);
      }
      case EnumMember {name, initializer}: {
        walk(name, enter, leave);
        if (initializer !== null) { walk(initializer, enter, leave); }
      }
      case CatchClause {param, body}: {
        if (param !== null) { walk(param, enter, leave); }
        walk(body, enter, leave);
      }
      case PropertySignature {name, typeAnnotation}: {
        walk(name, enter, leave);
        walk(typeAnnotation, enter, leave);
      }
      case ImportSpecifier {imported, local}: {
        walk(imported, enter, leave);
        walk(local, enter, leave);
      }
      // A leaf: a decorator's path and arguments are compile-time syntax,
      // and are never runtime values. Walking the arguments made
      // `@external("env", "print")` register "env" and "print" as string
      // constants of every program that declared an import.
      case Decorator {}: {}
      case ContractClause {condition}: {
        walk(condition, enter, leave);
      }
      case SymbolPropertyName {symbolRef}: {
        walk(symbolRef, enter, leave);
      }
      case _: {}
    }
  }
}

// ============================================================================
// Public API
// ============================================================================

/// Walk a node tree in pre+post order.
/// `enter` is called before children — return false to skip the subtree.
/// `leave` is called after children.
export function walk(node: Node, enter: (n: Node) => boolean, leave: (n: Node) => void): void {
  if (!enter(node)) { return; }
  walkChildren(node, enter, leave);
  leave(node);
}

/// Walk with an enter callback only (no leave). Visits every node.
export function walkEnter(node: Node, fn: (n: Node) => void): void {
  walk(node, (n) => { fn(n); return true; }, (n) => {});
}

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