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 function`s 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, `let`s and `var`s (`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 |
|
|