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

8.3 KiB Raw
import { Set, HashMap, HashSet } from 'zena:collections';
import { Type } from '../types.zena';
import { SymbolId } from '../scope/symbol.zena';
import { Node, SourceLocation } from '../ast.zena';

/**
 * The checker's control-flow graph (docs/design/ownership.md, "The checker
 * flow graph").
 *
 * Flow nodes are built by the checker as it walks a function body, in the
 * style of TypeScript's binder: each node points backward at its
 * antecedents, so a query walks from a use toward the function entry. The
 * graph is a side structure — it never replaces the AST, and it exists
 * per checked body, not per instantiation, which is what lets it serve
 * checking of code RTA later drops.
 *
 * The first consumer is narrowing validity: a narrowing records the flow
 * node where its guard established it, and a read walks backward from the
 * reference to that node, failing if some path crosses an assignment that
 * no longer satisfies the narrowed type. Move checking builds on the same
 * nodes.
 *
 * Nodes compare by `id`, never by `==`: joins make the graph cyclic
 * through loop back edges, so structural equality must not be reachable.
 */
export sealed class FlowNode {
  case FlowStart, FlowAssign, FlowMove, FlowNarrowings, FlowJoin,
    FlowUnreachable, FlowSuspend

  /** Unique within one CheckerContext; minted by the checker. */
  var id: i32 = 0;
}

/**
 * Entry of a function body (or of the module's top level). `enclosing`
 * is the flow at the closure's creation site in the enclosing body, so
 * a walk can keep going for a captured binding — a closure sees the
 * narrowings that held where it was written.
 */
export final class FlowStart extends FlowNode {
  var enclosing: FlowNode | null = null;

  /**
   * Whether this body shares `this` with its enclosing body (a closure
   * inside a method does; a method, accessor or top-level body starts a
   * fresh `this`). A `this`-rooted path walk stops where `this` stops.
   */
  var sharesThis: boolean = false;
}

/**
 * Follows code that cannot be reached — after `return`, `throw`,
 * `break`, `continue`. Joins drop unreachable antecedents.
 */
export final class FlowUnreachable extends FlowNode {}

/**
 * An assignment to a local binding. `assignedType` is the checked type of
 * the stored value; null means the type was unavailable, which a validity
 * walk must treat as incompatible.
 */
export final class FlowAssign extends FlowNode {
  antecedent: FlowNode;
  symbolId: SymbolId;
  assignedType: Type | null;

  /**
   * Set for a store into a member path a dispose moved out (`this.field`),
   * which revives it; such a node carries `noSymbolId`, so the symbol
   * walks pass through it. Empty for binding assignments.
   */
  var pathKey: String = "";
  new(this.antecedent, this.symbolId, this.assignedType) : super();
}

/**
 * A move of an owned binding: passed to an `Own` parameter, moved into
 * another binding, or consumed by a `this: Own<this>` method. The binding
 * is dead on every path through this node until a reassignment revives
 * it. `loc` is where the move happened, for the use-after-move message
 * and for the loop back-edge report.
 */
export final class FlowMove extends FlowNode {
  antecedent: FlowNode;
  symbolId: SymbolId;
  name: String;
  loc: SourceLocation | null;

  /**
   * Set for a move of a member path (`this.field` in a consuming
   * method) instead of a binding; such a node carries `noSymbolId`, so
   * the symbol walks pass through it. Empty for binding moves.
   */
  var pathKey: String = "";
  /**
   * Set for the mark an `isFirstClass<T>()` branch leaves on each `T`
   * value at its entry: on that path `T` is first-class, so the value
   * counts as consumed (the required-consumption walk stops here), yet
   * it is not dead, and a later use is no use after move.
   */
  var consumesOnly: boolean = false;
  new(this.antecedent, this.symbolId, this.name, this.loc) : super();
}

/**
 * The narrowings a condition (or match pattern) establishes on the path
 * it guards: what the checker's condition engine computed for one
 * branch, attached to that branch's entry. A backward walk takes the
 * nearest node mentioning its binding or path — composition of nested
 * guards is already baked in, because the engine computes each map from
 * the types that held where the condition sits.
 */
export final class FlowNarrowings extends FlowNode {
  antecedent: FlowNode;
  bindings: HashMap<SymbolId, Type>;
  paths: HashMap<String, Type>;
  new(this.antecedent, this.bindings, this.paths) : super();
}

/**
 * A merge point: the end of an `if`, a loop header, a `match` join, the
 * short-circuit join of `&&`/`||`/`??`, or a `catch` entry (whose
 * antecedents include every assignment in the protected body). Loop
 * headers gain their back edge after the body is walked.
 */
export final class FlowJoin extends FlowNode {
  antecedents = new Array<FlowNode>();

  /** Unreachable antecedents carry no paths, so they are not recorded. */
  add(node: FlowNode): void {
    if (node is FlowUnreachable) { return; }
    this.antecedents.push(node);
  }
}

/**
 * A suspension point: an `await` or a `yield`. Transparent to
 * narrowing and to move liveness; a second-class borrow read on a path
 * through one has outlived the extent it was borrowed from —
 * ownership.md §"Borrows and suspension".
 */
export final class FlowSuspend extends FlowNode {
  antecedent: FlowNode;
  new(this.antecedent) : super();
}

/**
 * One read of a second-class borrow inside a suspending body, checked
 * when the body's flow graph is complete (loop back edges included):
 * a suspension on any backward path from the read to the binding's
 * birth is the error.
 */
export final class BorrowUseRec {
  symbolId: SymbolId;
  name: String;
  node: FlowNode;
  exprNodeId: i32;
  loc: SourceLocation | null;
  new(this.symbolId, this.name, this.node, this.exprNodeId, this.loc);
}

/**
 * One if/else whose arms may need compensating drops (ownership.md
 * §"The branch-join rule"): recorded while checking, decided when the
 * enclosing scope closes and every capture and escape is known. The
 * arm-end flow nodes let the decision ask, per binding, whether a move
 * lies on one arm and not the other.
 */
export final class PendingEdgeIf {
  ifNode: Node;
  preBranch: FlowNode;
  trueEnd: FlowNode;
  falseEnd: FlowNode;
  trueReachable: boolean;
  falseReachable: boolean;
  new(this.ifNode, this.preBranch, this.trueEnd, this.falseEnd,
      this.trueReachable, this.falseReachable);
}

/**
 * One match whose arms may need compensating drops: the N-ary sibling
 * of PendingEdgeIf. Arm ends align with the match's cases by index; a
 * diverged arm's end is FlowUnreachable and needs no compensation.
 */
export final class PendingEdgeMatch {
  matchNode: Node;
  preBranch: FlowNode;
  armEnds: GrowableArray<FlowNode>;
  new(this.matchNode, this.preBranch, this.armEnds);
}

/**
 * An early exit — a `return`, `break` or `continue` — recorded for the
 * same decision: the flow where control leaves, and the depth of the
 * innermost own scope it leaves (a `return` leaves the body's, a `break`
 * or `continue` those inside its loop). A binding released at none of
 * its scope's ends, because some path moves it, is released here when
 * it is still live (ownership.md §"The branch-join rule").
 */
export final class PendingExit {
  exitNode: Node;
  flow: FlowNode;
  fromDepth: i32;
  new(this.exitNode, this.flow, this.fromDepth);
}

/**
 * The checker's per-body flow state, saved and restored around nested
 * function bodies the way return/yield context is: a closure checked in
 * the middle of an enclosing body gets its own FlowStart and its own
 * loop and exception stacks.
 */
export final class FlowBodyState {
  current: FlowNode;
  start: FlowStart;
  loopHeads: GrowableArray<FlowJoin>;
  loopExits: GrowableArray<FlowJoin>;
  exceptionTargets: GrowableArray<FlowJoin>;
  loopMoves: GrowableArray<GrowableArray<FlowMove>>;
  loopDeclared: GrowableArray<HashSet<i32>>;
  pendingEdgeIfs: GrowableArray<PendingEdgeIf>;
  var borrowUses = new Array<BorrowUseRec>();
  var pendingEdgeMatches = new Array<PendingEdgeMatch>();
  var pendingExits = new Array<PendingExit>();
  var bodyExits = new Array<FlowNode>();
  var bodyPathMoves = new Array<FlowMove>();
  var scopedBodyFloor: i32 = 0;
  var scopedLoopFloorCount: i32 = 0;
  new(this.current, this.start, this.loopHeads, this.loopExits,
      this.exceptionTargets, this.loopMoves, this.loopDeclared,
      this.pendingEdgeIfs);
}

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