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 Rendered 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 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.
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19