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

14.3 KiB Source Raw

The type checker (lib/checker/)#

The checker walks a module's AST, infers types, validates them, and writes what it learned into the module's SemanticModel. The AST is never mutated except for one case: a call or new whose arguments are fewer than the callee's parameters gets the callee's default initializers spliced into its argument list (splicedArgCountOf records how many the caller wrote).

An expression's type is recorded on the expression's node. A type annotation inside an expression gets a type of its own only where the checker writes one: x is T records T on the annotation, while x as T records it on the AsExpression alone, so getNodeType(asExpr.typeAnnotation) is null.

lib/checker.zena is the public surface: checkModule, beginModule, finishModule, ModuleCheck, CheckResult, SharedCheckerState, typesEqual, isNullableType, unwrapAliases. Everything else lives here. The libraries import each other freely and form one import cycle, like codegen/ir/; the rules for what may cross a cycle are in docs/design/import-cycles.md. In practice: every function one of these libraries exports needs its parameter and return types written out, and a module-level let is read only by the library that declares it.

Checking a module#

Checking has two halves (module.zena). beginModule registers every declaration's signature: imports, classes, interfaces, enums, mixins, type aliases, declare functions and symbols. After it, every type identity and member signature in the module exists, so a method body can call a method of a class declared further down. finishModule checks the bodies, then binds the module's exports. A module outside any import cycle runs the two back to back; the members of a cycle all begin before any finishes. A dependency module leaves its function and member bodies for reachability to ask for (DeferredModule, docs/design/lazy-body-checking.md).

Name resolution for values delegates to the scope pass's ReferenceMap: an identifier resolves to a Symbol, and the symbol's binding type is stored in and read back from the SemanticModel. Type declarations are materialized on demand, by symbol identity, the first time anything names them (CheckerContext.#materializeFromSymbol); a declaration has exactly one type object however many modules or passes ask for it (SharedCheckerState.declaredNominalTypes).

Library map#

Library Holds
context.zena SharedCheckerState (what one compilation shares across modules) and CheckerContext (one module's check): type materialization, binding and reference resolution, the per-body context (return, yield and async types), the flow graph and its narrowing and move walks, the implicit-drop verdicts, diagnostics.
module.zena checkModule, beginModule, finishModule; DeferredModule; the compiler intrinsics the prelude does not declare; the import-cycle rules for one imported name.
annotations.zena resolveTypeAnnotation: a type annotation node to a Type, with the inline-tuple, row-parameter and resource-mention rules.
unions.zena createUnionType and the union rules (representation mixing, handle merging, class members folding into interface members, discriminated tuples); unwrapAliases, subtractNullFromType.
relations.zena isAssignableTo, typesEqual, isValidCast and the other cast rules (opaque types, type-parameter minting), the representation predicates (isValuePrimitive, isReferenceType, ...).
generics.zena substituteTypeParams, type-argument inference (inferTypeArg), constraint checking (applyAndCheckTypeArguments), instantiateGenericClass and instantiateGenericInterface.
adaptation.zena checkAndRegisterInterfaceAdaptation: where a value crosses a representation boundary (class to interface, function re-wrapping, record repacking), recorded for codegen.
ownership.zena The ownership rules (docs/design/ownership.md): second-class storage, affine values, moves (recordArgumentMove), owner-field moves, the implicit-drop candidates, requireDisposable.
contracts.zena The rules for contract clauses (docs/design/contracts.md): requires and ensures conditions on a function, with result and old(e), and invariant conditions on a loop. A static condition and an old argument are recorded as a PurityObligation, which compiler.zena settles after every library is checked (../../../CONTEXT.md, "Purity Is Decided After the Check").
inline.zena The rule for inline parameters, lets and vars (docs/design/inline-parameters.md): a walk of each body that declares one, classifying every reference by its parent node as a read, a forward or a use that would box it (checkInlineBindingUses), an inline var's writes outside protected regions, and the function-value and signature rules (rejectInlineFunctionValue, inlineParamsMatch).
protocols.zena The iteration and future protocols: getIterationProtocol for for-in, Iterator<T>, AsyncIterator<T> and Future<T> construction and inspection.
narrowing.zena What a condition narrows (getNarrowedTypesFromCondition), member-path keys, and the definitely-exits analysis.
literals.zena Numeric literal typing against context (checkIntegerLiteral), and whether a literal argument adapts to a parameter.
overloads.zena Overload applicability and most-specific selection, for calls and operators.
expressions.zena checkExpression: literals, identifiers, assignment, if, casts, is, array, record, tuple and map literals, templates, throw, try, ranges, pipelines; checkBinaryExpression; checkAwaitExpression.
members.zena Member keys (name-keyed and symbol-keyed), checkMemberExpression, resolveMemberType, index expressions, static symbols.
calls.zena checkCallExpression and checkNewExpression: argument checking, default splicing, generic calls.
functions.zena checkFunctionExpression: arrows and function bodies, contextual parameter typing, generators and async bodies, captures.
statements.zena checkStatement: declarations, return, yield, loops, if, imports and re-exports, using, tail returns.
patterns.zena bindPattern (irrefutable) and checkPattern (refutable): record, tuple, array and class patterns, and the type a bare class name in a pattern stands for.
match.zena checkMatchExpr and exhaustiveness: what each arm's pattern subtracts from the scrutinee's type.
classes.zena registerClassDeclaration (signatures, inheritance, case classes, mixin application, field decorators) and checkClassBodies (initializers, member bodies, interface conformance, the resource rules); checkMethodSignature, checkMethodBody, checkSuperInitArgs.
declarations.zena Interfaces and their constructors, type aliases and type operators, enums, mixins and decorators, declare function, symbol.

The flow graph#

CheckerContext builds a control-flow graph (analysis/flow.zena) as it walks a body: assignments, moves, narrowings, suspensions and joins advance currentFlow. A reference's type is its declared type refined by a backward walk from the reference to the body's entry (flowTypeOfBinding, flowTypeOfPath), and use-after-move checking walks the same nodes (findLiveMove). The walks memoize per join and invalidate the entries a loop's back edge can change; see the comments on #walkBindingType.

Well-known types#

The checker never decides what a standard library type is from its name. ctx.tryResolveWellKnownType(WellKnown.X) answers with the declaration the library owns (well-known.zena), and isWellKnown compares a type's name and declaring library. The remaining name-based sites are listed in elematic/zena#288.

Surveying a rule#

To see where a proposed rule would fire before it becomes an error, report each site with a temporary ctx.warning(...), build stage A (npm run build:cli -w @zena-lang/compiler-zena), and compile the code to survey with it through ZENA_COMPILER_WASM (packages/compiler/CONTEXT.md, "Debugging the compiler"), with ZENA_WARN_UNNECESSARY_CASTS=1 ZENA_CHECK_ALL_BODIES=1 set. Despite its name, the first variable makes the compile print warnings of every kind; without it none are printed (compile-file.zena). The second checks every body of the standard library and the other dependencies and reports what it finds there; otherwise a dependency's bodies are checked only when reached, and its diagnostics are dropped.

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