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

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