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

7.0 KiB Raw
import {
  Module, VariableDeclaration, FunctionDeclaration, MixinDeclaration, DeclareFunction, IdentifierPattern,
} from './ast.zena';
import { SemanticModel, ModelIndex } from './semantic-model.zena';
import { Symbol } from './scope/symbol.zena';
import { stdlibModuleNameForEntryPath } from './stdlib-manifest.zena';

export type CompilationUnit = {
  ast: Module,
  model: SemanticModel
};

/**
 * An immutable snapshot of a single compilation state.
 * Encapsulates the compilation units and entry point.
 */
export final class Program {
  // This array maintains topological ordering guarantees from the compiler
  // pipeline, which is necessary for sequential WebAssembly code emission.
  // Although a tree walk (DFS) over a module dependency graph could derive
  // the order dynamically, doing the topological sort once up front and storing
  // it prevents redundant walks during code generation.
  units: GrowableArray<CompilationUnit>;
  unitsByPath = new Map<String, CompilationUnit>();
  entryPoint: CompilationUnit | null;

  /**
   * Who owns each node and binding. Not built here: it belongs to the
   * check that produced these models, which is also what lets a model
   * be shared by every compile in a batch without any of them writing
   * to it. A `Program` over models from more than one check — which
   * the compiler never builds — would see only the first's.
   */
  var modelIndex = new ModelIndex();

  mixinDeclarations = new Map<String, MixinDeclaration>();
  exportedSymbols = new Map<String, GrowableArray<Symbol>>();
  exportedFunctions = new Map<String, GrowableArray<DeclareFunction>>();

  new(this.units, this.entryPoint = null) {
    // Adopted from the check, never built here. The empty index the
    // field initializer supplies stands in only for a `Program` over
    // models that were never checked, which is a test fixture.
    if (this.units.length > 0) {
      let fromCheck = this.units[0].model.index;
      if (fromCheck != null) {
        this.modelIndex = fromCheck;
      }
    }
    for (let u in this.units) {
      this.unitsByPath[u.ast.path] = u;
      if (u.ast.path.startsWith("/")) {
        this.unitsByPath[u.ast.path.sliceBytes(1, u.ast.path.length)] = u;
      } else {
        this.unitsByPath["/" + u.ast.path] = u;
      }
      // A stdlib unit is keyed by its canonical id, which for a module
      // with a `path` or `virtual` manifest entry is a path id
      // ("zena:wasi/index.zena", "zena:console/host.zena").
      // Imports name the module ("zena:wasi"), so index that
      // spelling too — from the manifest, so only real entry files get a
      // module name and private files get none. Deriving it from the file
      // name instead produced "zena:zena:stream" for a top-level
      // path id, which is why the reachability import resolver needed a
      // filename-suffix search to find these at all.
      if (u.ast.path.startsWith("zena:")) {
        let entryPath = u.ast.path.sliceBytes(5, u.ast.path.length);
        let moduleName = stdlibModuleNameForEntryPath(entryPath);
        if (moduleName != null) {
          this.unitsByPath["zena:" + (moduleName as String)] = u;
        }
      }
      // Precompute mixin declarations and export maps
      for (let stmt in u.ast.body) {
        match (stmt) {
          case MixinDeclaration as md: {
            this.mixinDeclarations[`${u.ast.path}::${md.name.name}`] = md;
          }
          case DeclareFunction as df: {
            let {name} = df.name;
            let key = `${u.ast.path}::${name}`;
            let arr = if (let (true, a) = this.exportedFunctions.get(key)) {
              a
            } else {
              let newArr = new Array<DeclareFunction>();
              this.exportedFunctions[key] = newArr;
              newArr
            };
            arr.push(df);

            let sym = u.model.resolveDeclaration(df);
            if (sym != null) {
              let symKey = `${u.ast.path}::${name}`;
              let symArr = if (let (true, sa) = this.exportedSymbols.get(symKey)) {
                sa
              } else {
                let newArr = new Array<Symbol>();
                this.exportedSymbols[symKey] = newArr;
                newArr
              };
              symArr.push(sym);
            }
          }
          case VariableDeclaration as vd: {
            match (vd.pattern) {
              case IdentifierPattern {name} as pat: {
                this.#recordValueBinding(u, pat, name);
              }
              case _: {}
            }
          }
          case FunctionDeclaration {name as namePat}: {
            this.#recordValueBinding(u, namePat, namePat.name);
          }
          case _: {}
        }
      }
    }
  }

  /**
   * The unit this compile linked for `path`, or null.
   *
   * `path` is a library path as a Symbol carries it, which for a virtual
   * library is the implementation its own compile resolved —
   * `zena:console/host.zena`, not `zena:console`. A compile for another
   * target linked a different library under that name, so a direct
   * lookup would miss. Mapping the path id back to the name finds
   * whichever implementation *this* compile has, which is what a shared
   * check result will need: the model names the library, and the unit
   * answering for it is the target's.
   *
   * The manifest already indexes every virtual implementation path under
   * its name (`buildLibraryIndex`), so the reverse hop is a lookup
   * rather than a search.
   */
  unitFor(path: String): CompilationUnit | null {
    if (let (true, unit) = this.unitsByPath.get(path)) {
      return unit;
    }
    if (!path.startsWith("zena:")) {
      return null;
    }
    let moduleName = stdlibModuleNameForEntryPath(
        path.sliceBytes(5, path.length));
    if (moduleName == null) {
      return null;
    }
    return this.unitsByPath.get(`zena:${moduleName}`) ?? null;
  }

  /**
   * Record a module-level value binding (a `let`/`var` name or a
   * `function` declaration's name) under both its file path key and, for
   * stdlib modules, its `zena:<name>` key.
   */
  #recordValueBinding(u: CompilationUnit, pat: IdentifierPattern, name: String): void {
    let sym = u.model.resolveDeclaration(pat);
    if (sym == null) { return; }
    let key = `${u.ast.path}::${name}`;
    let arr = if (let (true, a) = this.exportedSymbols.get(key)) {
      a
    } else {
      let newArr = new Array<Symbol>();
      this.exportedSymbols[key] = newArr;
      newArr
    };
    arr.push(sym);

    var lastSlash2 = -1;
    var idx2 = 0;
    while (idx2 < u.ast.path.length) {
      if (u.ast.path.getByteAt(idx2) == 47) { lastSlash2 = idx2; }
      idx2 += 1;
    }
    let fileName2 = if (lastSlash2 >= 0) u.ast.path.sliceBytes(lastSlash2 + 1, u.ast.path.length) else u.ast.path;
    if (fileName2.endsWith(".zena")) {
      let stdName2 = fileName2.sliceBytes(0, fileName2.length - 5);
      let stdKey = `zena:${stdName2}::${name}`;
      let stdArr = if (let (true, sa) = this.exportedSymbols.get(stdKey)) {
        sa
      } else {
        let newArr2 = new Array<Symbol>();
        this.exportedSymbols[stdKey] = newArr2;
        newArr2
      };
      stdArr.push(sym);
    }
  }

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