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

2.8 KiB Raw
import { Node, IdGenerator } from '../ast.zena';
import { Symbol, SymbolId, makeSymbolIdGenerator, noSymbolId } from './symbol.zena';
import { HashMap } from 'zena:collections';

/**
 * What kind of lexical scope this is.
 * Determines variable visibility rules and serves as documentation.
 */
export enum ScopeKind {
  Module,   // Top-level module scope
  Function, // Function or method body
  Block,    // Block statement, if/while/for body
  Class     // Class body (for `this`, type parameters)
}

/**
 * A lexical scope containing name bindings.
 *
 * Scopes are organized in a parent chain: each scope (except the module
 * root) has a parent scope. Name resolution walks the chain outward.
 */
export final class Scope {
  scopeKind: ScopeKind;
  parent: Scope | null;
  #bindings = new Map<String, Symbol>();
  var #symbolIdGenerator = makeSymbolIdGenerator();

  bindings: HashMap<String, Symbol> {
    get { return this.#bindings; }
  }

  new(this.scopeKind: ScopeKind, this.parent: Scope | null, symbolIdGenerator: IdGenerator<SymbolId> | null = null) {
    if (symbolIdGenerator != null) {
      this.#symbolIdGenerator = symbolIdGenerator;
    } else if (parent != null) {
      this.#symbolIdGenerator = parent.#symbolIdGenerator;
    }
  }

  /**
   * Declare a name in this scope.
   * Returns false if the name already exists in this scope (duplicate).
   */
  declare(
    name: String,
    isMutable: boolean,
    declaration: Node | null,
    modulePath: String,
    id: SymbolId = noSymbolId): boolean {
      
    if (this.#bindings.has(name)) {
      // TODO: This should be an error, but we call declare() multiple times
      // for overloads and sealed variants, which currently share the same name.
      // We should refactor to only call declare() once per unique name.
      return false;
    }
    let actualId = if (id != noSymbolId) id else this.#symbolIdGenerator.next();
    this.#bindings[name] = new Symbol(name, declaration, modulePath, isMutable, actualId);
    return true;
  }

  /**
   * Inject an existing Symbol into this scope.
   * Useful for constructing composite scopes like the prelude.
   */
  inject(name: String, info: Symbol): void {
    this.#bindings[name] = info;
  }

  /**
   * Look up a name in this scope only (no parent walk).
   */
  getLocal(name: String): Symbol | null {
    return if (let (true, info) = this.#bindings.get(name)) {
      info
    } else {
      null
    };
  }

  /**
   * Resolve a name by walking the scope chain outward.
   */
  resolve(name: String): Symbol | null {
    var current: Scope | null = this;
    while (current != null) {
      let scope = current;
      if (let (true, info) = scope.#bindings.get(name)) {
        return info;
      }
      current = scope.parent;
    }
    return null;
  }

  /**
   * Check if a name exists in this scope (not parents).
   */
  has(name: String): boolean {
    return this.#bindings.has(name);
  }
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19