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
19.1 KiB
Raw
import { Program } from '../../program.zena';
import { RecordDispatchInfo, WasmModule, WasmFunction, WasmStruct } from '../wasm-module.zena';
import { SemanticModel, SymbolDependencies } from '../../semantic-model.zena';
import { Type, ClassType, InterfaceType, FunctionType } from '../../types.zena';
import { WellKnown } from '../../well-known.zena';
import { Node, CallExpression, ClassDeclaration, InterfaceDeclaration, ImportDeclaration, VariableDeclaration, FunctionDeclaration, DeclareFunction } from '../../ast.zena';
import { Set, HashMap, HashSet } from 'zena:collections';
import { SymbolId } from '../../scope/symbol.zena';
import { WasmType } from '../wasm.zena';
import { MixinKey, ClassMethodKey, ClassKey, getClassKey } from '../codegen-utils.zena';
import { ClassHierarchyAnalysis } from './hierarchy.zena';
/**
* Referrer tracks the source and context of why a particular node or member
* was reached, allowing for detailed RTA dependency graphs.
*/
export final class Referrer {
isSymbol: boolean;
symId: SymbolId;
nodeId: i32;
model: SemanticModel;
classType: ClassType | null;
isReachable: boolean;
typeArguments: Array<Type> | null;
new(this.isSymbol, this.symId, this.nodeId, this.model, this.classType = null, this.isReachable = true, this.typeArguments = null);
}
/**
* One virtual use of a generic interface method: an interface
* specialization, the method, and one solved type-argument list. Each
* demand becomes one interface vtable slot, named with the same
* specialized-name mangle the class-side monomorphized copies register
* under, so the call site, the slot, and every implementing class's
* trampoline agree on the name.
*/
export final class GenericInterfaceMethodDemand {
interfaceType: InterfaceType;
methName: String;
slotName: String;
typeArgs: Array<Type>;
model: SemanticModel;
/** Whether the slot field has been appended to the interface's vtable struct. */
var slotAdded: boolean = false;
new(this.interfaceType, this.methName, this.slotName, this.typeArgs, this.model);
}
/**
* One virtual use of a generic class method: the hierarchy root class
* that introduces the method, the method name, the specialized slot
* name, and one solved type-argument list. Each demand adds one class
* vtable slot across the root class's hierarchy and specializes
* overrides on concrete subclasses.
*/
export final class GenericClassMethodDemand {
rootClass: ClassType;
methodName: String;
slotName: String;
typeArgs: Array<Type>;
model: SemanticModel;
syncedClasses = new Set<String>();
new(this.rootClass, this.methodName, this.slotName, this.typeArgs, this.model);
}
/**
* SpecializerInterface defines the monomorphization subsystem contract.
*/
export interface SpecializerInterface {
instantiateClassType(classType: ClassType, model: SemanticModel): void;
discoverStaticFields(classType: ClassType, cd: ClassDeclaration, model: SemanticModel): void;
instantiateGenericFunction(targetSymId: SymbolId, args: Array<Type>): WasmFunction;
/**
* The function behind `new I<args>.name(...)` for an interface
* constructor: one monomorphized copy per type-argument list, minted
* on first demand, like a generic top-level function's.
*/
instantiateInterfaceConstructor(
it: InterfaceType,
ctorName: String,
methodNode: Node,
model: SemanticModel
): WasmFunction;
instantiateGenericMethod(
ct: ClassType,
cd: Node | null,
methName: String,
methodNode: Node,
typeArgs: Array<Type>,
model: SemanticModel
): WasmFunction;
registerSpecializedClass(ct: ClassType, classDecl: Node | null, model: SemanticModel): void;
preRegisterClassStruct(ct: ClassType): boolean;
finishSpecializedClass(ct: ClassType, classDecl: Node | null, sourceModel: SemanticModel): void;
registerSpecializedInterface(it: InterfaceType, ifaceDecl: InterfaceDeclaration | null, sourceModel: SemanticModel): void;
preRegisterInterfaceStruct(it: InterfaceType): boolean;
finishSpecializedInterface(it: InterfaceType, ifaceDecl: InterfaceDeclaration | null, sourceModel: SemanticModel): void;
registerClassMethod(
cType: ClassType,
cDecl: Node | null,
methName: String,
methodNode: Node | null,
isSynthesizedGetter: boolean,
isSynthesizedSetter: boolean,
backingFieldName: String | null,
model: SemanticModel,
methodTypeArgs: Array<Type> | null = null
): WasmFunction;
populateClassStructAndMethods(ct: ClassType, cd: Node | null, sourceModel: SemanticModel): void;
refreshErasedFieldTypes(): void;
mintConstructorPhases(): void;
}
/**
* TypeLowererInterface defines the WebAssembly type-mapping subsystem contract.
*/
export interface TypeLowererInterface {
discoverType(t: Type | null, model: SemanticModel): void;
discoverSignatureType(t: Type | null, model: SemanticModel): void;
}
/**
* ReachabilityVisitorInterface defines the AST-visitation subsystem contract.
*/
export interface ReachabilityVisitorInterface {
/**
* AST nodes the discovery walk has entered. A queue item is a whole
* declaration, so items alone cannot say whether the walk is
* superlinear or the declarations are simply bigger; cost per node
* can.
*/
discoveredNodes: i32 { get; }
discoverNodeTypes(root: Node, model: SemanticModel, resolveType: (t: Type) => Type): void;
registerLiterals(root: Node): void;
/** Register a string literal the module will need, as a body's literal would be. */
noteStringLiteral(value: String): void;
registerInstantiations(root: Node, model: SemanticModel, resolveType: (t: Type) => Type, classType: ClassType | null): void;
discoverImportDeclaration(importDecl: ImportDeclaration, moduleModel: SemanticModel): void;
discoverVariableDeclaration(symId: SymbolId, varDecl: VariableDeclaration, moduleModel: SemanticModel): void;
discoverFunctionDeclaration(symId: SymbolId, funcDecl: FunctionDeclaration, moduleModel: SemanticModel): void;
discoverDeclareFunction(decl: DeclareFunction, moduleModel: SemanticModel): void;
registerWrapper(keyName: String, ft: FunctionType, targetWasmFunc: WasmFunction, model: SemanticModel): void;
discoverFunctionValueWrapper(ft: FunctionType, model: SemanticModel): void;
queueCancellationMachinery(futureType: ClassType, model: SemanticModel): void;
/** Registers structural `==` for two record or tuple types. */
noteValueEquality(lt: Type, rt: Type, model: SemanticModel): void;
/** Registers the hash of a record or tuple type. */
noteValueHash(t: Type, model: SemanticModel): void;
queueStdlibFunction(library: String, exportName: String): void;
}
/**
* ReachabilityContext defines the interface for the central compilation state coordinator,
* allowing child visitors and specializers to query and update the work queues without
* introducing circular module imports.
*/
/**
* The `recordLiteralArgs` key for argument `index` of a call to the
* function `callee`.
*/
/**
* The `recordLiteralCtorArgs` key for argument `index` of a `new` of
* constructor `method` (`<constructor>` or `<constructor>.name`) of the
* class whose key is `classKey`.
*/
export function recordLiteralCtorArgKey(classKey: String, method: String,
index: i32): String {
return `${classKey}.${method}#${index}`;
}
export function recordLiteralArgKey(callee: SymbolId, index: i32): i64 {
return ((callee as i32) as i64) * 65536 + (index as i64);
}
/**
* A direct call to a module-level function whose result is a record,
* for argument explosion's result analysis (ir/explode.zena).
*/
export final class RecordResultCall {
call: CallExpression;
model: SemanticModel;
callee: SymbolId;
/**
* For a method call, the method it resolves to (`methodTargetKey`;
* `callee` is then `noSymbolId`); null for a function call.
*/
var methodTarget: String | null = null;
/**
* For a call to a generic function, the name of the specialization it
* calls (`WasmFunction.name`); null otherwise.
*/
var specTarget: String | null = null;
new(this.call, this.model, this.callee);
}
/**
* A specialization of a generic method: the method's `methodTargetKey`
* with the specialized slot name (`getSpecializedName`, `map_spec_i32`)
* its solved type arguments name. One declaration is one function per
* class instantiation and per method instantiation.
*/
export function specMethodTargetKey(target: String, specMethodName: String): String {
return `${target}#${specMethodName}`;
}
/**
* The key of a record literal passed as argument `index` of a call to
* the specialization of a generic function named `specName`.
*/
export function recordLiteralSpecArgKey(specName: String, index: i32): String {
return `${specName}|${index}`;
}
/**
* A method as compiled: its declaration node in the instantiation of the
* class that declares it. One declaration in a generic class is one
* function per instantiation, so the node alone does not name it.
*/
export function methodTargetKey(methodNode: i32, declaring: ClassType): String {
return `${methodNode}@${getClassKey(declaring) as String}`;
}
/**
* The class in `ct`'s superclass chain whose declaration contains the
* method `md`, as instantiated along that chain: the class the method's
* function is registered under.
*/
export function declaringInstantiation(classDecls: HashMap<SymbolId, Node>,
ct: ClassType, md: Node): ClassType | null {
var c: ClassType | null = ct;
while (c != null) {
let cc = c;
if (!cc.isMixinIntermediate) {
let lookupId = (cc.genericSource ?? cc).symbolId;
if (let (true, decl) = classDecls.get(lookupId)) {
if (decl is ClassDeclaration) {
for (let member in decl.body) {
if ((member as Node) === md) {
return cc;
}
}
}
}
}
c = cc.superType;
}
return null;
}
/**
* The `recordLiteralMethodArgs` key for argument `index` of a direct call
* of the method `target` (`methodTargetKey`).
*/
export function recordLiteralMethodArgKey(target: String, index: i32): String {
return `${target}#${index}`;
}
export interface ReachabilityContext {
isRtaActive: boolean;
var instantiationClosed: boolean;
instantiatedSpecializedClasses: HashSet<String>;
instantiatedClasses: HashSet<SymbolId>;
/**
* Class keys REACHED CODE NAMES — recorded by discoverType during a
* reachable traversal. A lowered body can reference a class struct
* in a cast, a type test, or a field read on a nullable reference
* without the module ever constructing a value, so instantiation
* alone under-approximates which structs the type section needs;
* declaration (all of classInfos) wildly over-approximates it.
*/
reachablyNamedClasses: HashSet<String>;
ctorDemandedGenerics: HashSet<SymbolId>;
var equalityDispatchUsed: boolean;
/** A closed record type an `as` converts an existential to at run time. */
noteExistentialCastTarget(target: RecordDispatchInfo): void;
notePendingStaticTargets(t: Type, memberName: String): void;
/** Reaches what releasing a `t` calls (`releaseOwned<T>`). */
noteReleaseTargets(t: Type, model: SemanticModel): void;
var inQueueWalk: boolean;
/**
* True while discovery is running for a REGISTRATION's signature —
* plumbing that computes wasm types for members that may never be
* reached. Name evidence (reachablyNamedClasses, composite notes) is
* suppressed under it: a reached body re-records its own evidence
* when it is walked, and a registered-but-unreached member's
* signature kept four Range structs in a module whose only code is
* an index loop.
*/
var suppressNameEvidence: boolean;
/**
* True while a class with no emission evidence is being laid out.
*
* Every declared class in every loaded module gets a struct layout,
* whether or not the module emits it — the layout is what registers
* its members, and a class can pick up evidence after its turn. But
* laying one out walks its members' signatures, and a signature
* mention of `Completer<i32>` is not a `new Completer<i32>()`. Under
* this flag such a mention still registers the specialization, so
* fields and signatures can name its struct, and stops there: it
* does not instantiate it, and `currentReachable` is false alongside
* so it does not fan the generic's reached members out over it
* either. Reached code records its own evidence when it is walked.
*/
var layingOutUnemittedClass: boolean;
/**
* The generic TEMPLATE whose member the queue walk is inside, if any.
* A template's members are walked to register them and to fan out a
* concrete referrer per specialization — the body itself is never
* emitted, so what it constructs constructs nothing. An EMITTED body
* is the opposite: `fill_spec_erased` really does run its `new`.
* Null inside a concrete class, a free function, or no walk at all.
*/
var walkingTemplateOf: ClassType | null;
/**
* Closure structs reached code can reference: recorded where RTA
* mints one for a genuine value position (discoverType's
* FunctionType arm, wrappers, adaptations) under the same evidence
* gate as reachablyNamedClasses. The tail roots THESE rather than
* every closure struct ever interned — plumbing walks mint shapes
* nothing emitted refers to, each dragging its impl signature into
* the type section.
*/
reachablyNamedClosures: HashSet<WasmStruct>;
noteClosureStruct(cs: WasmStruct): void;
noteCompositeType(t: Type): void;
/** Anonymous (boxed tuple/record) structs named by reached code (same gate). */
reachablyNamedAnonStructs: HashSet<WasmStruct>;
specializedClassTypes: HashMap<SymbolId, GrowableArray<ClassType>>;
/**
* Insertion-ordered (OrderedHashMap, values unused): these node-id sets
* are REPLAYED into the queues per specialization, so their
* iteration order becomes function emission order. Node ids are a
* relabelling across invalidate() — hashing by id made the same
* program emit differently after an invalidate that changed nothing.
*/
reachedClassMembers: HashMap<SymbolId, HashMap<i32, boolean>>;
reachedReachableClassMembers: HashMap<SymbolId, HashMap<i32, boolean>>;
currentReachable: boolean;
classDecls: HashMap<SymbolId, Node>;
classModels: HashMap<SymbolId, SemanticModel>;
interfaceDecls: HashMap<SymbolId, InterfaceDeclaration>;
interfaceModels: HashMap<SymbolId, SemanticModel>;
program: Program;
wasm: WasmModule;
/** Whether a reached body can cause a cancellation — the
* whole-program gate the async machinery is emitted under. */
cancellationPossible: boolean;
/** Whether the cancellation machinery has been minted and queued. */
cancellationMachineryActive: boolean;
/** Every async function's frame Future instantiation, recorded so a
* cause discovered late still equips every frame. */
asyncFrameFutures: GrowableArray<Type>;
asyncFrameFutureModels: GrowableArray<SemanticModel>;
symbolIdToModel: HashMap<SymbolId, SemanticModel>;
symbolIdToDecl: HashMap<SymbolId, Node>;
symbolIdToTargetId: HashMap<SymbolId, SymbolId>;
nodeIdToNode: HashMap<i32, Node>;
nodeIdToModel: HashMap<i32, SemanticModel>;
reachedGlobals: HashSet<SymbolId>;
reachedMembers: HashSet<String>;
reachedFunctionsSet: HashSet<WasmFunction>;
specializedInterfaces: GrowableArray<InterfaceType>;
/**
* Demands for virtual generic-method slots, in discovery order.
* `demandGenericInterfaceMethod` records one per (interface
* specialization, solved type-argument list); the class-interface
* vtable pass appends the slots and builds the trampolines.
*/
genericInterfaceMethodDemands: GrowableArray<GenericInterfaceMethodDemand>;
demandGenericInterfaceMethod(it: InterfaceType, methName: String, typeArgs: Array<Type>, model: SemanticModel): void;
findGenericInterfaceDemand(iKey: String, slotName: String): GenericInterfaceMethodDemand | null;
genericClassMethodDemands: GrowableArray<GenericClassMethodDemand>;
demandGenericClassMethod(
classType: ClassType,
methodName: String,
typeArgs: Array<Type>,
model: SemanticModel): void;
mixinToClasses: HashMap<MixinKey, GrowableArray<ClassType>>;
cha: ClassHierarchyAnalysis;
specializer: SpecializerInterface;
typeLowerer: TypeLowererInterface;
visitor: ReachabilityVisitorInterface;
discoveredTypes: HashSet<String>;
reachedSemanticTypes: HashSet<String>;
/**
* The parameters some reached direct call passes a record literal,
* keyed by `recordLiteralArgKey`. Argument explosion
* (ir/explode.zena) splits only these.
*/
recordLiteralArgs: HashSet<i64>;
/** The same for constructors, keyed by `recordLiteralCtorArgKey`. */
recordLiteralCtorArgs: HashSet<String>;
recordLiteralMethodArgs: HashSet<String>;
/**
* The same for calls to generic functions, per specialization, keyed
* by `recordLiteralSpecArgKey`.
*/
recordLiteralSpecArgs: HashSet<String>;
/** Reached direct calls whose result is a record, once each. */
recordResultCalls: GrowableArray<RecordResultCall>;
/** The node ids of `recordResultCalls`, to keep it to one entry per call. */
recordResultCallIds: HashSet<i32>;
recordResultMethodCalls: HashSet<String>;
queueReferrer(ref: Referrer): void;
noteSpecialization(ct: ClassType, model: SemanticModel): void;
markFunctionReached(func: WasmFunction): void;
noteExceptionInfra(model: SemanticModel): void;
notePendingMemberReach(key: ClassMethodKey): void;
noteEqualityBase(ct: ClassType): void;
useEqualityDispatch(): void;
reachEqualityOf(ct: ClassType): void;
reachEqualityBelowComparedBase(ct: ClassType): void;
noteHostImportSignature(ft: FunctionType): void;
forceReachFunction(func: WasmFunction): void;
traverseDependencies(deps: SymbolDependencies, model: SemanticModel, classType: ClassType | null, typeArguments: Array<Type> | null, node: Node | null): void;
markTypeReached(t: WasmType | null): void;
getClassModel(ct: ClassType): SemanticModel;
getClassDeclType(classDecl: Node, model: SemanticModel): ClassType | null;
/** A well-known standard library class or interface, by identity:
* null when no unit of the program declares it. */
findPreludeClass(w: WellKnown): ClassType | null;
findPreludeInterface(w: WellKnown): InterfaceType | null;
getNodeModel(node: Node, defaultModel: SemanticModel): SemanticModel;
/**
* Records that reachable code calls `memberName` (a method name, or a
* `get#`/`set#` accessor name) through a value of interface `it`. Only
* such members get interface vtable slots.
*/
demandInterfaceMember(it: InterfaceType, memberName: String): void;
/**
* Records that reachable code reads the class-interface vtable of `c`
* at `i`: it packs a `c` into an `i`, or a type test against `i` can
* see a `c`. Only that specialization of the pair gets a vtable. A
* pair that still holds a type parameter or an erasure marks nothing:
* the walks under each substitution mark the specializations.
*/
demandPackPair(c: ClassType, i: InterfaceType): void;
/** Whether reachable code reads the class-interface vtable of `c` at `i`. */
isPackPairUsed(c: ClassType, i: InterfaceType): boolean;
/**
* Records that reachable code destructures with an array pattern,
* which reads the length and elements of an interface-typed value
* through its vtable (ir/patterns.zena) whatever the interface.
*/
noteArrayPattern(): void;
}
- 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 |
|
|