compiler 0.0.2-preview.1
The Zena self-hosted compiler
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.jsonmanifest 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
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.
- zena-lang:wit-parser wit-parser.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|