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

9.7 KiB Raw
import { Set } from 'zena:collections';
import {
  Node, Identifier, ThisExpression, AssignmentExpression, FunctionExpression, Parameter, VariableDeclaration, IdentifierPattern, Module, ClassDeclaration, InterfaceDeclaration, EnumDeclaration, MixinDeclaration, MethodDefinition, BlockStatement, WhileStatement, ForStatement, ForInStatement,
} from '../ast.zena';
import { SemanticModel } from '../semantic-model.zena';
import { Symbol, SymbolId } from '../scope/symbol.zena';
import { walkEnter } from '../visitor.zena';

export class CaptureInfo {
  captures = new Array<Symbol>();
  mutableCaptures = new Set<SymbolId>();
  var capturesThis: boolean = false;


}

function isLocalSymbol(sym: Symbol, model: SemanticModel): boolean {
  if (sym.declaration == null) { return false; }
  let decl = sym.declaration as Node;
  if (decl is Parameter) { return true; }

  var curr = decl;
  while (true) {
    let parent = model.getParent(curr);
    if (parent == null) { return false; }
    match (parent) {
      case Module: { return false; }
      case ClassDeclaration: { return false; }
      case InterfaceDeclaration: { return false; }
      case EnumDeclaration: { return false; }
      case MixinDeclaration: { return false; }
      case VariableDeclaration: {
        let varDeclParent = model.getParent(parent);
        if (varDeclParent == null) { return false; }
        match (varDeclParent) {
          case Module: { return false; }
          case ClassDeclaration: { return false; }
          case InterfaceDeclaration: { return false; }
          case MixinDeclaration: { return false; }
          case _: { return true; }
        }
      }
      case MethodDefinition: { return true; }
      case FunctionExpression: { return true; }
      case BlockStatement: { return true; }
      case _: {
        curr = parent;
      }
    }
  }
  return false;
}

function isDeclaredInClosure(sym: Symbol, funcExpr: FunctionExpression, model: SemanticModel): boolean {
  if (sym.declaration == null) { return false; }
  let decl = sym.declaration as Node;
  if (decl is Parameter) {
    for (let p in funcExpr.params) {
      if (p.id == decl.id) {
        return true;
      }
    }
  }
  var curr = decl;
  while (true) {
    let parent = model.getParent(curr);
    if (parent == null) { return false; }
    if (parent.id == funcExpr.id) {
      return true;
    }
    curr = parent;
  }
  return false;
}

/**
 * True when the symbol is captured before its binding initializes: its
 * declaration is the closure's own binding (`let visit = () => …
 * visit() …` — the closure sits inside the initializer) or a later
 * statement in the enclosing scope (`let a = () => b(); let b = …`).
 * Such captures must be celled: the cell exists (empty) before the
 * closure is created, and the declaration later writes through it.
 */
function isCapturedBeforeInit(s: Symbol, func: FunctionExpression, model: SemanticModel): boolean {
  if (s.declaration == null) { return false; }
  let decl = s.declaration as Node;
  if (decl is Parameter) { return false; }
  // Parser node ids are assigned in source order, so a declaration with
  // a larger id than the closure node is a forward reference.
  if ((decl.id as i32) > (func.id as i32)) { return true; }
  // Self-capture: the closure appears inside the symbol's own
  // initializer.
  var curr: Node = func;
  while (true) {
    let parent = model.getParent(curr);
    if (parent == null) { return false; }
    if (let VariableDeclaration {pattern} = parent) {
      match (pattern) {
        case IdentifierPattern as pat: {
          let ps = model.resolveDeclaration(pat);
          if (ps != null && ps.id == s.id) { return true; }
        }
        case _: {}
      }
    }
    curr = parent;
  }
  return false;
}

/** True when `sym`'s declaration sits anywhere inside `root`'s subtree. */
function isDeclaredWithin(sym: Symbol, root: Node, model: SemanticModel): boolean {
  if (sym.declaration == null) { return false; }
  var curr = sym.declaration as Node;
  while (true) {
    if (curr.id == root.id) { return true; }
    let parent = model.getParent(curr);
    if (parent == null) { return false; }
    curr = parent;
  }
  return false;
}

/**
 * True when an assignment to `sym` can run after `closure` is created,
 * while the closure still holds the same variable: one later in the
 * source (`last` is the textually last assignment), one whose value
 * contains the closure (`n = f(() => n)`), or any assignment at all
 * when a loop encloses the closure but not the declaration, because
 * the next iteration's assignments follow this iteration's closure. A
 * `for` header's variable is fresh on each iteration (lowerFor), so the
 * loop that declares it does not count.
 */
function assignedAfter(sym: Symbol, closure: Node, last: i32, model: SemanticModel): boolean {
  if (last > (closure.id as i32)) { return true; }
  var curr = closure;
  while (true) {
    let parent = model.getParent(curr);
    if (parent == null) { return false; }
    match (parent) {
      case AssignmentExpression {left}: {
        if (left is Identifier) {
          let target = model.resolve(left);
          if (target != null && target.resolveTarget().id == sym.id) { return true; }
        }
      }
      case WhileStatement: {
        if (!isDeclaredWithin(sym, parent, model)) { return true; }
      }
      case ForStatement: {
        if (!isDeclaredWithin(sym, parent, model)) { return true; }
      }
      case ForInStatement: {
        if (!isDeclaredWithin(sym, parent, model)) { return true; }
      }
      case _: {}
    }
    curr = parent;
  }
  return false;
}

/**
 * True when the closures that capture this local share it with its
 * declaring scope through a heap cell, rather than each copying its
 * value when created. A closure captures the variable, so it needs the
 * cell whenever the variable can change after some closure has
 * captured it: a closure assigns it, a closure is created before its
 * declaration runs (both in `mutablyCapturedSymbols`), or the
 * declaring scope assigns it after creating a closure. A variable only
 * ever assigned before the first capture reads the same either way,
 * and keeps its copy.
 *
 * One answer per variable, not per closure: every closure that
 * captures a celled variable must hold the same cell. Asked by code
 * generation, after the declaring body has been checked in full.
 */
export function capturedInCell(symId: SymbolId, model: SemanticModel): boolean {
  if (model.mutablyCapturedSymbols.has(symId)) { return true; }
  if (let (true, last) = model.lastAssignment.get(symId)) {
    if (let (true, local) = model.capturedLocals.get(symId)) {
      for (let closure in local.closures) {
        if (assignedAfter(local.sym, closure, last, model)) { return true; }
      }
    }
  }
  return false;
}

/**
 * Locals assigned inside a `try` body that are declared OUTSIDE it.
 *
 * These must live in heap cells, for the same reason a closure-mutated
 * capture does. The handler is entered from an arbitrary point in the
 * body's dynamic extent, so a value threaded along the protected edge
 * can only carry the state at `try` entry — every assignment the body
 * completed before it threw would be invisible to the handler and to
 * the code after the `try`. A cell is written in place, so both see
 * the last value written.
 *
 * Consumed by RTA (which interns the cell struct and registers the
 * symbol as celled); lowering then routes reads and writes through the
 * cell with no further knowledge of `try`.
 */
export function analyzeTryBodyAssignments(tryBody: Node, model: SemanticModel): GrowableArray<SymbolId> {
  let out = new Array<SymbolId>();
  let seen = new Set<SymbolId>();
  walkEnter(tryBody, (n) => {
    if (!(n is AssignmentExpression)) { return; }
    if (!(n.left is Identifier)) { return; }
    let symOpt = model.resolve(n.left as Identifier);
    if (symOpt == null) { return; }
    // Lowering asks `isCelled` about the resolve TARGET, so the set has
    // to be keyed the same way.
    let sym = symOpt.resolveTarget();
    if (seen.has(sym.id)) { return; }
    if (!isLocalSymbol(sym, model)) { return; }
    if (isDeclaredWithin(sym, tryBody, model)) { return; }
    seen.add(sym.id);
    out.push(sym.id);
  });
  return out;
}

export function analyzeCaptures(func: FunctionExpression, model: SemanticModel): CaptureInfo {
  let info = new CaptureInfo();
  let seen = new Set<SymbolId>();

  // Collect the referenced variables that are declared outside, from
  // the body and from the conditions of the function's contract
  // clauses, which run in its frame too.
  let visit = (n: Node) => {
    match (n) {
      case Identifier as ident: {
        let sym = model.resolve(ident);
        if (sym != null && isLocalSymbol(sym, model)) {
          if (!isDeclaredInClosure(sym, func, model)) {
            if (!seen.has(sym.id)) {
              seen.add(sym.id);
              info.captures.push(sym);
            }
            if (isCapturedBeforeInit(sym, func, model)) {
              info.mutableCaptures.add(sym.id);
            }
          }
        }
      }
      case ThisExpression: {
        info.capturesThis = true;
      }
      case AssignmentExpression as assign: {
        if (assign.left is Identifier) {
          let ident = assign.left as Identifier;
          let sym = model.resolve(ident);
          if (sym != null && isLocalSymbol(sym, model)) {
            if (!isDeclaredInClosure(sym, func, model)) {
              if (!seen.has(sym.id)) {
                seen.add(sym.id);
                info.captures.push(sym);
              }
              info.mutableCaptures.add(sym.id);
            }
          }
        }
      }
      case _: {}
    }
  };
  walkEnter(func.body, visit);
  let {contracts} = func;
  if (contracts != null) {
    for (let clause in contracts) {
      walkEnter(clause, visit);
    }
  }

  return info;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19