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
42.5 KiB
Raw
/**
* The component's imported interfaces, encoded by the WIT type encoder.
*
* The emitter used to hand-write each imported interface's instance
* type — possible only while every signature was flat scalars. Now the
* shape's imports are rendered as a WIT document and pushed through
* `wit-parser`'s component encoder, the same code path that round-trips
* real WIT through `wasm-tools component wit`. For scalar interfaces
* the bytes are identical to the hand-written ones; what changes is
* what becomes *possible*, because the encoder already speaks records,
* variants, resources and `use`, and the emitter no longer has an
* opinion.
*
* The derivation is per-interface WIT text, not per-program: each
* `@external("ns:pkg/iface@ver", "field")` group becomes an interface
* in a nested package, and a synthetic world imports them all. When an
* interface's true WIT is richer than a Zena declaration can spell
* (resources, lists — stdio's case), this is where its real source
* will be substituted for the derived one.
*/
import { StringBuilder } from 'zena:core';
import { parse, parseSyntax, resolve } from 'zena-lang:wit-parser';
import {
ComponentTypeEncoder, EncodedWorld, funcFlatMeta, worldFuncFlatMeta,
interfaceExportFlatMeta, WitFuncMeta, expandedWorldItems,
worldNames, qualifiedInterfaceName, NestedExport
} from 'zena-lang:wit-parser/component-encoder';
import {
Ast, AstItemTag, WorldDef, WorldItemTag, Import, Export, ExternKind,
ExternKindTag, UsePath, UsePathTag, Id, Func, Type, TypeTag, PackageName,
AstItem, InterfaceDef, InterfaceItem, InterfaceItemTag, NamedFunc, TypeDef, TypeDefTag,
ResourceFunc, ResourceFuncTag, NestedPackage, Docs, Use
} from 'zena-lang:wit-parser/parser';
import {
ComponentShape, ComponentImportFunc, ComponentExportFunc,
ComponentFuncType, noComponentResult, EncodedImports, EncodedImportPiece,
ImportTypeEncoder, ExportedInstanceType, NestedInstanceExport,
NestedInstanceArg, ResourceDtorSlot
} from './component-emitter.zena';
import { HashMap } from 'zena:collections';
/** The WIT spelling of a flat-scalar component value type opcode. */
function scalarWitName(opcode: i32): String {
if (opcode == 0x7f) { return "bool"; }
if (opcode == 0x7e) { return "s8"; }
if (opcode == 0x7d) { return "u8"; }
if (opcode == 0x7c) { return "s16"; }
if (opcode == 0x7b) { return "u16"; }
if (opcode == 0x7a) { return "s32"; }
if (opcode == 0x79) { return "u32"; }
if (opcode == 0x78) { return "s64"; }
if (opcode == 0x77) { return "u64"; }
if (opcode == 0x76) { return "f32"; }
if (opcode == 0x75) { return "f64"; }
if (opcode == 0x74) { return "char"; }
if (opcode == 0x73) { return "string"; }
// Only the shape builder produces these opcodes, and it only
// produces the scalars and string; anything else is a bug there.
throw new Error(
"no WIT spelling for component type opcode " + i32ToString(opcode));
}
/** One imported interface: its qualified name split into WIT's parts. */
final class InterfacePath {
/** `ns:pkg`, the package half. */
packageName: String;
/** The interface's own name. */
interfaceName: String;
/** The `@version`, or empty. */
version: String;
new(this.packageName, this.interfaceName, this.version);
}
function splitInterfaceName(name: String) {
var slash = -1;
for (var i = 0; i < name.length; i += 1) {
if (name.getByteAt(i) == 47) { // '/'
slash = i;
}
}
if (slash < 0) {
throw new Error(
"The component target cannot import from '" + name +
"': a WIT interface is named ns:pkg/interface, optionally with " +
"@version, and this has no '/'.");
}
let packageName = name.sliceBytes(0, slash);
var rest = name.sliceBytes(slash + 1, name.length);
var version = "";
var at = -1;
for (var i = 0; i < rest.length; i += 1) {
if (rest.getByteAt(i) == 64) { // '@'
at = i;
}
}
if (at >= 0) {
version = rest.sliceBytes(at + 1, rest.length);
rest = rest.sliceBytes(0, at);
}
return new InterfacePath(packageName, rest, version);
}
/** One function of an interface, as WIT source. */
function renderFunc(sb: StringBuilder, f: ComponentImportFunc) {
let sig = f.signature;
sb.append(" ").append(f.fieldName).append(": ");
if (sig.isAsync) {
sb.append("async ");
}
sb.append("func(");
for (var i = 0; i < sig.paramTypes.length; i += 1) {
if (i > 0) {
sb.append(", ");
}
sb.append(sig.paramNames[i]).append(": ")
.append(scalarWitName(sig.paramTypes[i]));
}
sb.append(")");
if (sig.result != noComponentResult) {
sb.append(" -> ").append(scalarWitName(sig.result));
}
sb.append(";\n");
}
/** The name of the synthetic world the derived document declares. */
let derivedWorldName = "imports";
/**
* Whether a parsed document declares the interface `qualified` names —
* package, interface and version all matching. This is what makes a
* WIT-backed package's interfaces "provided": their real source
* substitutes for the derived spelling, exactly as the compiler's own
* baked WASI blocks do.
*/
/**
* The WIT-backed packages' document, parsed once per source text. The
* stdlib's vendored WASI is most of it, and every component compiled
* in a process reads the same text: a test runner compiling hundreds
* of programs paid a parse of the corpus for each, and the parse was
* nearly all of the compile.
*/
var memoPackagesWit = "";
var memoPackagesAst: Ast | null = null;
function packagesAstOf(packagesWit: String): Ast | null {
if (packagesWit == "") {
return null;
}
let cached = memoPackagesAst;
if (cached != null && memoPackagesWit == packagesWit) {
return cached;
}
let parsed = parse(packagesWit);
memoPackagesWit = packagesWit;
memoPackagesAst = parsed;
return parsed;
}
/**
* Add the packages `packages` declares to `into`, as nested packages:
* what splicing their text at the end of `into`'s document parsed to,
* when the document was built as text. The corpus's main package is
* wrapped; its nested ones are shared as they are.
*/
function addPackages(into: Ast, packages: Ast) {
let main = packages.packageName;
if (main != null) {
let name = main as PackageName;
var docs = packages.packageDocs;
if (docs == null) {
docs = new Docs(name.span);
}
let pkg = new NestedPackage(docs as Docs, name);
pkg.items = packages.items;
into.nestedPackages.push(pkg);
}
for (let nested in packages.nestedPackages) {
into.nestedPackages.push(nested);
}
}
/** Whether `ast` declares the package `ns:pkg@version`, in its main
* package or a nested one. */
function docDeclaresPackage(ast: Ast, packageKey: String): boolean {
let keyOf = (pkg: PackageName | null) => {
if (pkg == null) {
return "";
}
let p = pkg as PackageName;
var key = `${p.namespace.name}:${p.name.name}`;
if (p.version != null) {
key = `${key}@${p.version as String}`;
}
return key;
};
if (keyOf(ast.packageName) == packageKey) {
return true;
}
for (let nested in ast.nestedPackages) {
if (keyOf(nested.name) == packageKey) {
return true;
}
}
return false;
}
function docDeclaresInterface(ast: Ast, qualified: String): boolean {
let path = splitInterfaceName(qualified);
let matches = (pkg: PackageName | null, items: GrowableArray<AstItem>): boolean => {
if (pkg == null) {
return false;
}
let p = pkg as PackageName;
if (`${p.namespace.name}:${p.name.name}` != path.packageName) {
return false;
}
let version = if (p.version != null) p.version as String else "";
if (version != path.version) {
return false;
}
for (let item in items) {
if (item.tag != AstItemTag.Interface) {
continue;
}
if ((item.interfaceDef as InterfaceDef).name.name ==
path.interfaceName) {
return true;
}
}
return false;
};
if (matches(ast.packageName, ast.items)) {
return true;
}
for (let nested in ast.nestedPackages) {
if (matches(nested.name, nested.items)) {
return true;
}
}
return false;
}
/**
* The shape's imports as a WIT document: one interface per `@external`
* namespace, grouped into their packages, and a world importing each.
*
* `packagesWit` is the concatenated source of the program's WIT-backed
* packages. An interface it declares is spliced whole rather than
* derived, like the compiler's own baked WASI blocks — the synthesized
* declarations for such interfaces are canonically flattened core
* shapes, and deriving from those would declare the flattening as the
* interface's type.
*/
export function deriveImportsWit(
shape: ComponentShape,
packagesWit: String = ""
): String {
let packagesAst = packagesAstOf(packagesWit);
let provided = (name: String) =>
packagesAst != null && docDeclaresInterface(packagesAst as Ast, name);
// Group by interface, preserving first-appearance order (the same
// grouping the emitter's aliases use), then group interfaces by
// package for the nested-package declarations.
let interfaceNames = new Array<String>();
for (let imp in shape.imports) {
var seen = false;
for (let n in interfaceNames) {
if (n == imp.interfaceName) { seen = true; }
}
if (!seen) { interfaceNames.push(imp.interfaceName); }
}
let sb = new StringBuilder();
sb.append("package zena:derived;\n\n");
// Interfaces whose real WIT a WIT-backed package carries — the
// stdlib's vendored WASI, a manifest package's — are not derived:
// `encodeImportTypes` adds the packages' parsed document to this
// one, and the world imports them by name like any other.
let renderedPackages = new Array<String>();
for (let name in interfaceNames) {
if (provided(name)) { continue; }
let path = splitInterfaceName(name);
let packageKey = `${path.packageName}@${path.version}`;
if (packagesAst != null &&
docDeclaresPackage(packagesAst as Ast, packageKey)) {
throw new Error(
"The component target cannot import '" + name + "': its package " +
"is one the program's WIT-backed packages carry real WIT for, " +
"and this interface is not in it.");
}
var rendered = false;
for (let p in renderedPackages) {
if (p == packageKey) { rendered = true; }
}
if (rendered) { continue; }
renderedPackages.push(packageKey);
sb.append("package ").append(path.packageName);
if (path.version != "") {
sb.append("@").append(path.version);
}
sb.append(" {\n");
// Every interface of this package, in first-appearance order.
for (let other in interfaceNames) {
if (provided(other)) { continue; }
let otherPath = splitInterfaceName(other);
if (`${otherPath.packageName}@${otherPath.version}` != packageKey) {
continue;
}
sb.append(" interface ").append(otherPath.interfaceName)
.append(" {\n");
for (let imp in shape.imports) {
if (imp.interfaceName == other) {
renderFunc(sb, imp);
}
}
sb.append(" }\n");
}
sb.append("}\n\n");
}
sb.append("world ").append(derivedWorldName).append(" {\n");
for (let name in interfaceNames) {
sb.append(" import ").append(name).append(";\n");
}
sb.append("}\n");
return sb.toString();
}
/**
* Encode the shape's imported interfaces; the emitter's front matter.
*
* Also the point where WIT-provided imports meet the document: each is
* checked to actually exist in its interface, and its flattening
* decides whether the lowering carries the canonical memory options.
* An empty import list encodes to an empty world — no pieces, every
* count zero — so the caller need not special-case it. A typed
* `task.return` (a `return:` canon type) is still encoded then, against
* a world with no imports: an async `main` returning a `String` needs
* its `string` type whether or not the program imports anything.
*/
export function encodeImportTypes(
shape: ComponentShape,
packagesWit: String = ""
): EncodedImports {
var typedReturn = false;
for (let b in shape.builtins) {
if (b.canonType.startsWith("return:")) { typedReturn = true; }
}
if (shape.imports.length == 0 && !typedReturn) {
return new EncodedImports();
}
let text = deriveImportsWit(shape, packagesWit);
// Resolved once the packages are in: the derived world imports
// their interfaces by name.
let ast = parseSyntax(text);
let packagesAst = packagesAstOf(packagesWit);
if (packagesAst != null) {
addPackages(ast, packagesAst as Ast);
}
resolve(ast);
for (let imp in shape.imports) {
if (!imp.witProvided) {
continue;
}
let meta = funcFlatMeta(ast, imp.interfaceName, imp.fieldName);
if (meta == null) {
throw new Error(
"The component target cannot import '" + imp.fieldName +
"' from '" + imp.interfaceName + "': the interface's WIT " +
"declares no such function.");
}
imp.needsMemoryLower = (meta as WitFuncMeta).needsMemory;
}
let encoder = new ComponentTypeEncoder(ast);
let world = encoder.encodeWorld(derivedWorldName);
let canonTypes = resolveCanonTypes(encoder, shape);
// Mirrored after everything is encoded: the canon types appended
// component-level types the count has to include.
let out = mirrorEncodedWorld(world);
copyIndices(canonTypes, out.canonTypeIndices);
return out;
}
/** Copy every entry of `from` into `into`. */
function copyIndices(from: HashMap<String, i32>,
into: HashMap<String, i32>): void {
let keys = from.keys();
for (let key in keys) {
into[key] = from[key];
}
}
/**
* The type immediates the canon builtins need, by their `canonType`
* spelling. A `resource.drop`'s type is the imported instance's own,
* reachable only through an alias the encoder appends; a
* `future:<interface>#<payload-wit>` is the future's own component
* type, its payload's named types alias-exported from the interface's
* imported instance; a `return:<interface>#<type-wit>` is the result
* type a typed `task.return` carries, named against the interface, or
* structural at the component level when the interface is empty.
* Resolved after the world so the instances exist, before mirroring so
* the alias pieces travel. The FIRST '#' splits — a qualified interface
* name contains none, a type may.
*/
function resolveCanonTypes(
encoder: ComponentTypeEncoder,
shape: ComponentShape
): HashMap<String, i32> {
let indices = new Map<String, i32>();
let split = (canonType: String, prefixLength: i32,
expected: String): (String, String) => {
let spec = canonType.sliceBytes(prefixLength, canonType.length);
var hashAt = -1;
for (var i = 0; i < spec.length; i += 1) {
if (spec.getByteAt(i) == 35) { hashAt = i; break; } // '#'
}
if (hashAt < 0) {
throw new Error("Malformed canon type '" + canonType +
"' (expected " + expected + ")");
}
return (spec.sliceBytes(0, hashAt),
spec.sliceBytes(hashAt + 1, spec.length));
};
for (let b in shape.builtins) {
let canonType = b.canonType;
if (indices.has(canonType)) { continue; }
if (canonType.startsWith("resource:")) {
let (iface, name) = split(canonType, 9, "resource:<interface>#<name>");
indices[canonType] = encoder.aliasResourceType(iface, name);
} else if (canonType.startsWith("future:")) {
let (iface, payload) =
split(canonType, 7, "future:<interface>#<payload>");
indices[canonType] = encoder.aliasFutureType(iface, payload);
} else if (canonType.startsWith("stream:")) {
let (iface, element) =
split(canonType, 7, "stream:<interface>#<element>");
indices[canonType] = encoder.aliasStreamType(iface, element);
} else if (canonType.startsWith("return:")) {
let (iface, text) = split(canonType, 7, "return:<interface>#<type>");
indices[canonType] = encoder.encodeTypeText(iface, text);
}
}
return indices;
}
/** `EncodedWorld`, mirrored into codegen's own classes. */
function mirrorEncodedWorld(world: EncodedWorld): EncodedImports {
let out = new EncodedImports();
for (let piece in world.pieces) {
out.pieces.push(new EncodedImportPiece(piece.id, piece.payload));
}
out.typeCount = world.typeCount;
out.instanceCount = world.instanceCount;
for (let slot in world.dtorSlots) {
out.dtorSlots.push(new ResourceDtorSlot(slot.qualified, slot.name));
}
let names = world.instanceIndices.keys();
for (let name in names) {
out.instanceIndices[name] = world.instanceIndices[name];
}
let exporting = world.exportedTypes.keys();
for (let iface in exporting) {
let mirrored = new GrowableArray<ExportedInstanceType>();
for (let t in world.exportedTypes[iface]) {
mirrored.push(new ExportedInstanceType(t.name, t.index));
}
out.exportedTypes[iface] = mirrored;
}
return out;
}
/**
* The default encoder: no world was declared, so each interface's WIT
* is derived from the Zena declarations, except for the interfaces the
* compiler carries real source for.
*/
final class DerivedImportEncoder implements ImportTypeEncoder {
/** The concatenated WIT of the program's WIT-backed packages. */
#packagesWit: String;
new(packagesWit: String = "") : #packagesWit = packagesWit;
witProvided(interfaceName: String): boolean {
let packagesAst = packagesAstOf(this.#packagesWit);
return packagesAst != null &&
docDeclaresInterface(packagesAst as Ast, interfaceName);
}
encode(shape: ComponentShape): EncodedImports {
return encodeImportTypes(shape, this.#packagesWit);
}
}
/** The WIT spelling of a declared export's WIT type, for messages. */
function witTypeName(t: Type) {
let opcode = exportableWitOpcode(t);
if (opcode >= 0) {
return scalarWitName(opcode);
}
return "<not a flat scalar or string>";
}
/**
* The component opcode of a WIT type a program export can carry today —
* the flat scalars and `string` — or -1. Richer world exports need the
* marshaling C-track work and are rejected by name.
*/
function exportableWitOpcode(t: Type): i32 {
if (t.tag == TypeTag.Bool) { return 0x7f; }
if (t.tag == TypeTag.S8) { return 0x7e; }
if (t.tag == TypeTag.U8) { return 0x7d; }
if (t.tag == TypeTag.S16) { return 0x7c; }
if (t.tag == TypeTag.U16) { return 0x7b; }
if (t.tag == TypeTag.S32) { return 0x7a; }
if (t.tag == TypeTag.U32) { return 0x79; }
if (t.tag == TypeTag.S64) { return 0x78; }
if (t.tag == TypeTag.U64) { return 0x77; }
if (t.tag == TypeTag.F32) { return 0x76; }
if (t.tag == TypeTag.F64) { return 0x75; }
if (t.tag == TypeTag.String) { return 0x73; }
return -1;
}
/**
* Parse a declared world's document, with the program's WIT-backed
* packages riding along so a world can `import wasi:cli/stdout@0.3.0;`
* without vendoring it — unless the document declares those packages
* itself, in which case its definitions win and theirs stay out of the
* way.
*/
function parseWithWasi(witSource: String, packagesWit: String = "") {
return parse(withWasiPackages(witSource, packagesWit));
}
/**
* `witSource` with the program's WIT-backed packages appended — the
* stdlib's vendored WASI among them — so a declared world can import
* their interfaces by name (`wasi:cli/stdout`, `wasi:http/types`)
* without vendoring them. Unless the document declares one of those
* packages itself, in which case its definitions win and the packages
* stay out of the way, all of them: a document that vendors a package
* is taken to be self-contained.
*/
/**
* `witSource` with the program's WIT-backed packages appended — the
* stdlib's vendored WASI among them — so a declared world can import
* their interfaces by name (`wasi:cli/stdout`, `wasi:http/types`)
* without vendoring them. Packages that `witSource` already declares
* are omitted so they do not conflict.
*/
export function withWasiPackages(witSource: String,
packagesWit: String = ""): String {
if (packagesWit == "") {
return witSource;
}
let lines = packagesWit.split("\n");
let sb = new StringBuilder();
sb.append(witSource);
var currentSkipping = false;
var hasAppended = false;
for (let line in lines) {
if (line.startsWith("package ")) {
var end = line.length;
for (var i = 8; i < line.length; i += 1) {
let c = line.getByteAt(i);
if (c == 59 || c == 32 || c == 123) { end = i; break; } // ';' ' ' '{'
}
let name = line.sliceBytes(0, end);
currentSkipping = witSource.contains(name + ";") || witSource.contains(name + " {");
}
if (!currentSkipping) {
if (!hasAppended) {
sb.append("\n");
hasAppended = true;
}
sb.append(line).append("\n");
}
}
return sb.toString();
}
/**
* One function export a declared world demands of the program: a
* world-level function, or a function of an exported interface, whose
* qualified name is `instanceName` (empty at world level).
*/
final class DeclaredExport {
name: String;
func: Func;
instanceName: String;
new(this.name, this.func, this.instanceName = "");
}
/**
* The encoder for a program compiled against a declared world
* (`--wit`/`--world`): the world is the authority, emission follows it,
* and every disagreement between the WIT and the Zena program is a
* compile error.
*
* Concretely: the component imports exactly what the world imports,
* with its `include`s expanded (expandedWorldItems), plus the interfaces
* those imports and the world's exports `use` types from, which WIT
* implies; every `@external` must name a function of one of those
* interfaces, with a core signature matching the WIT's canonical
* flattening; and the
* export surfaces must agree in both directions — a world export the
* program does not provide, or a program export the world does not
* declare, is an error, as is a type or asyncness mismatch on one they
* share.
*/
final class DeclaredWorldEncoder implements ImportTypeEncoder {
#ast: Ast;
var #worldName = "";
/**
* The world's interface imports, by qualified name: the ones it names,
* then the ones they and its exports `use` types from.
*/
#importedInterfaces = new Array<String>();
/** The world's exported interfaces, by qualified name. */
#exportedInterfaces = new Array<String>();
/** The world's function exports, in declaration order. */
#declaredExports = new Array<DeclaredExport>();
new(witSource: String, worldName: String, packagesWit: String = "")
: #ast = parseWithWasi(witSource, packagesWit) {
var name = worldName;
if (name == "") {
let names = worldNames(this.#ast);
if (names.length != 1) {
var listed = "";
for (let n in names) {
if (listed != "") { listed = listed + ", "; }
listed = `${listed}'${n}'`;
}
throw new Error(if (names.length == 0) {
"--wit names a document with no world; declare one, or pass " +
"--world if it lives in another file."
} else {
"--wit names a document with more than one world (" + listed +
"); say which with --world."
});
}
name = names[0];
}
this.#worldName = name;
var found = false;
for (let item in this.#ast.items) {
if (item.tag != AstItemTag.World) { continue; }
let world = item.worldDef as WorldDef;
if (world.name.name != name) { continue; }
found = true;
for (let wi in expandedWorldItems(this.#ast, world)) {
if (wi.tag == WorldItemTag.Import) {
this.#collectImport((wi.importItem as Import).kind);
} else if (wi.tag == WorldItemTag.Export) {
this.#collectExport((wi.exportItem as Export).kind);
}
// use / typedef fail in the encoder with their own messages;
// collecting nothing here keeps that the one error.
}
}
if (!found) {
throw new Error("--world '" + name + "' is not a world the --wit " +
"document declares.");
}
this.#addUsedInterfaces();
}
/**
* Adds the interfaces the world's imports and exports `use` types
* from, and the ones those use, to its imports. WIT imports each of
* them whether or not the world names it, and so does the encoder, so
* a program may call into one: the stdlib's `wasi:http/service` world
* reaches `types` only through `client` and `handler`.
*/
#addUsedInterfaces(): void {
let pending = new Array<String>();
for (let q in this.#importedInterfaces) { pending.push(q); }
for (let q in this.#exportedInterfaces) { pending.push(q); }
var i = 0;
while (i < pending.length) {
let qualified = pending[i];
i += 1;
for (let used in this.#usedInterfaces(qualified)) {
var known = false;
for (let q in this.#importedInterfaces) {
if (q == used) { known = true; }
}
if (!known) {
this.#importedInterfaces.push(used);
pending.push(used);
}
}
}
}
/** The interfaces the interface `qualified` uses types from, by qualified name. */
#usedInterfaces(qualified: String): GrowableArray<String> {
let used = new Array<String>();
let collect = (pkg: PackageName | null, items: GrowableArray<AstItem>) => {
for (let item in items) {
if (item.tag != AstItemTag.Interface) { continue; }
let def = item.interfaceDef as InterfaceDef;
if (qualifiedInterfaceName(pkg, def.name.name) != qualified) { continue; }
for (let member in def.items) {
if (member.tag != InterfaceItemTag.Use) { continue; }
let from = (member.use as Use).from;
used.push(if (from.tag == UsePathTag.Id) {
qualifiedInterfaceName(pkg, (from.id as Id).name)
} else {
qualifiedInterfaceName(from.packageId, (from.name as Id).name)
});
}
}
};
collect(this.#ast.packageName, this.#ast.items);
for (let nested in this.#ast.nestedPackages) {
collect(nested.name, nested.items);
}
return used;
}
#collectImport(kind: ExternKind): void {
if (kind.tag == ExternKindTag.Path) {
let path = kind.path as UsePath;
let qualified = if (path.tag == UsePathTag.Id) {
qualifiedInterfaceName(this.#ast.packageName, (path.id as Id).name)
} else {
qualifiedInterfaceName(path.packageId, (path.name as Id).name)
};
this.#importedInterfaces.push(qualified);
} else if (kind.tag == ExternKindTag.Interface) {
// An inline interface imports under its plain name.
this.#importedInterfaces.push((kind.name as Id).name);
}
// A world-level function import is legal WIT and is encoded, but a
// program has no way to bind one yet — `@external` names an
// interface and a field — so it is import surface the program
// simply does not call.
}
#collectExport(kind: ExternKind): void {
if (kind.tag == ExternKindTag.Func) {
this.#declaredExports.push(
new DeclaredExport((kind.name as Id).name, kind.funcDef as Func));
return;
}
if (kind.tag == ExternKindTag.Path) {
// An exported interface: the component exports an instance of
// that name, and each of the interface's functions is one export
// the program provides, lifted into it.
let path = kind.path as UsePath;
let qualified = if (path.tag == UsePathTag.Id) {
qualifiedInterfaceName(this.#ast.packageName, (path.id as Id).name)
} else {
qualifiedInterfaceName(path.packageId, (path.name as Id).name)
};
let items = this.#interfaceItems(qualified);
if (items == null) {
throw new Error("The declared world exports '" + qualified +
"', which the document does not declare.");
}
this.#exportedInterfaces.push(qualified);
for (let item in items as GrowableArray<InterfaceItem>) {
if (item.tag == InterfaceItemTag.Func) {
let nf = item.func as NamedFunc;
this.#declaredExports.push(
new DeclaredExport(nf.name.name, nf.func, qualified));
} else if (item.tag == InterfaceItemTag.TypeDef &&
(item.typeDef as TypeDef).tag == TypeDefTag.Resource) {
// A resource is a class of the program's; its constructor,
// methods and statics are exports under the canonical ABI's
// mangled names, each implemented by a wrapper the compiler
// writes around the class.
let td = item.typeDef as TypeDef;
let resourceName = td.name.name;
for (let rf in td.resourceFuncs as GrowableArray<ResourceFunc>) {
let exported = if (rf.tag == ResourceFuncTag.Constructor) {
"[constructor]" + resourceName
} else if (rf.tag == ResourceFuncTag.Method) {
`[method]${resourceName}.${rf.func.name.name}`
} else {
`[static]${resourceName}.${rf.func.name.name}`
};
this.#declaredExports.push(
new DeclaredExport(exported, rf.func.func, qualified));
}
}
}
return;
}
throw new Error("The declared world exports an inline interface, " +
"which a program cannot implement yet.");
}
/** The items of the interface `qualified` declares, or null. */
#interfaceItems(qualified: String): GrowableArray<InterfaceItem> | null {
for (let item in this.#ast.items) {
if (item.tag != AstItemTag.Interface) { continue; }
let def = item.interfaceDef as InterfaceDef;
if (qualifiedInterfaceName(this.#ast.packageName, def.name.name) ==
qualified) {
return def.items;
}
}
for (let nested in this.#ast.nestedPackages) {
for (let item in nested.items) {
if (item.tag != AstItemTag.Interface) { continue; }
let def = item.interfaceDef as InterfaceDef;
if (qualifiedInterfaceName(nested.name, def.name.name) == qualified) {
return def.items;
}
}
}
return null;
}
witProvided(interfaceName: String): boolean {
return true;
}
encode(shape: ComponentShape): EncodedImports {
this.#checkImports(shape);
this.#checkExports(shape);
let encoder = new ComponentTypeEncoder(this.#ast);
let world = encoder.encodeWorld(this.#worldName);
let canonTypes = resolveCanonTypes(encoder, shape);
// An async export's lifted type is the WIT's, encoded here rather
// than derived from a core signature: its parameters and result
// may be any WIT type the wrapper marshals. Its memory need
// decides the lift's options, and its typed return's, together.
let exportTypes = new Map<String, i32>();
for (let e in shape.exports) {
if (!e.witTyped) { continue; }
var meta: WitFuncMeta | null = null;
if (e.instanceName == "") {
exportTypes[e.typeKey()] =
encoder.encodeWorldExportFuncType(this.#worldName, e.exportName);
meta = worldFuncFlatMeta(this.#ast, this.#worldName, e.exportName);
} else {
exportTypes[e.typeKey()] = encoder.encodeExportedInterfaceFuncType(
e.instanceName, e.exportName);
meta = interfaceExportFlatMeta(this.#ast, e.instanceName,
e.exportName);
}
if (meta != null) {
let m = meta as WitFuncMeta;
e.needsMemoryLift = m.needsMemory;
// A synchronous lift returns at most one core value; a result
// flattening past that comes back as a return area's address,
// which the host reads and then hands to `post-return`.
e.needsPostReturnLift = !m.isAsync && m.resultFlatCount > 1;
// The return area is in linear memory, so such a lift carries the
// memory options whether or not any string or list is involved:
// `func() -> size`, two bare floats, needs them.
if (e.needsPostReturnLift) {
e.needsMemoryLift = true;
}
}
}
let out = mirrorEncodedWorld(world);
copyIndices(canonTypes, out.canonTypeIndices);
copyIndices(exportTypes, out.exportTypeIndices);
// An exported interface with a resource of its own is realized as
// a nested component (NestedInstanceExport): encoded here, after
// the world and every type the lifts name exist at component
// level, with the instance's exports in the order the emitter
// lifts them.
let instanceNames = new Array<String>();
for (let e in shape.exports) {
if (e.instanceName == "") { continue; }
var seen = false;
for (let name in instanceNames) {
if (name == e.instanceName) { seen = true; }
}
if (!seen) { instanceNames.push(e.instanceName); }
}
for (let name in instanceNames) {
if (!encoder.interfaceDeclaresResource(name)) { continue; }
let exportNames = new Array<String>();
for (let e in shape.exports) {
if (e.instanceName == name) { exportNames.push(e.exportName); }
}
let nested = encoder.encodeExportedInterfaceComponent(name, exportNames);
let mirrored = new NestedInstanceExport(nested.bytes);
for (let t in nested.typeImports) {
mirrored.typeArgs.push(new NestedInstanceArg(t.name, t.outerIndex));
}
for (let f in nested.funcImports) {
mirrored.funcImports.push(f);
}
out.nestedExports[name] = mirrored;
}
return out;
}
/**
* Every `@external` must name a function of an interface the world
* explicitly imports, and the Zena declaration's core signature must
* match the WIT's canonical flattening. The flattening determines
* counts, not core value types, so this is a count-level check —
* enough to catch a missing retptr, a forgotten parameter, or a sync
* declaration against an async function.
*/
#checkImports(shape: ComponentShape): void {
for (let imp in shape.imports) {
var declared = false;
for (let name in this.#importedInterfaces) {
if (name == imp.interfaceName) { declared = true; }
}
if (!declared) {
throw new Error("The program imports '" + imp.fieldName +
"' from '" + imp.interfaceName + "', which the declared " +
"world does not import. Add `import " + imp.interfaceName +
";` to the world, or drop the @external.");
}
let metaOpt = funcFlatMeta(this.#ast, imp.interfaceName, imp.fieldName);
if (metaOpt == null) {
throw new Error("The program imports '" + imp.fieldName +
"' from '" + imp.interfaceName + "', and the interface's WIT " +
"declares no such function.");
}
let meta = metaOpt as WitFuncMeta;
if (imp.lowerAsync != meta.isAsync) {
throw new Error("The program and the WIT disagree about whether '" +
imp.fieldName + "' of '" + imp.interfaceName + "' is async: " +
(if (meta.isAsync) {
"the WIT says async, so the @external needs the \"async\" " +
"option."
} else {
"the @external says async, and the WIT function is not."
}));
}
// The core signature the canonical ABI will call with: flattened
// parameters (or one pointer once they spill past sixteen), a
// trailing return-area address when the result flattens to more
// than one value, and for an async lowering a subtask handle as
// the one result.
var expectedParams =
if (meta.paramFlatCount > 16) 1 else meta.paramFlatCount;
var expectedResults = 0;
if (imp.lowerAsync) {
// The async lowering flattens at most four parameter core
// values before spilling all of them through one pointer, any
// result rides a trailing return-area address, and the one
// core result is the packed subtask.
expectedParams =
if (meta.paramFlatCount > 4) 1 else meta.paramFlatCount;
if (meta.resultFlatCount > 0) {
expectedParams += 1;
}
expectedResults = 1;
} else if (meta.resultFlatCount > 1) {
expectedParams += 1;
} else {
expectedResults = meta.resultFlatCount;
}
if (imp.coreParamCount != expectedParams ||
imp.coreResultCount != expectedResults) {
throw new Error("The @external declaration for '" + imp.fieldName +
"' of '" + imp.interfaceName + "' does not match the WIT's " +
"canonical flattening: the declaration has " +
i32ToString(imp.coreParamCount) + " parameter(s) and " +
i32ToString(imp.coreResultCount) + " result(s), and the " +
"flattening needs " + i32ToString(expectedParams) +
" and " + i32ToString(expectedResults) + ".");
}
imp.needsMemoryLower = meta.needsMemory;
}
}
/**
* The export surfaces must agree exactly: name for name, type for
* type, and async for async. The world's export types are limited to
* what the program can marshal today — flat scalars and `string` —
* and anything richer is rejected by name rather than emitted as a
* lift the wrappers cannot satisfy.
*/
#checkExports(shape: ComponentShape): void {
for (let declared in this.#declaredExports) {
var found = false;
for (let e in shape.exports) {
if (e.exportName == declared.name) { found = true; }
}
if (!found) {
throw new Error("The declared world exports '" + declared.name +
"', and the program does not export it.");
}
}
for (let e in shape.exports) {
var declaredOpt: DeclaredExport | null = null;
for (let d in this.#declaredExports) {
if (d.name == e.exportName) { declaredOpt = d; }
}
if (declaredOpt == null) {
throw new Error("The program exports '" + e.exportName +
"', which the declared world does not export. Add `export " +
e.exportName + ": func(...);` to the world, or stop " +
"exporting it.");
}
let declared = declaredOpt as DeclaredExport;
// The export lands in the instance the world puts it in. Names
// are matched across the world's exports as a whole, so one
// name in two exported interfaces is not supported yet.
e.instanceName = declared.instanceName;
if (declared.func.isAsync) {
// Implemented through the wrapper the compiler wrote for it
// (wit-module-synth's `synthesizeExportWrapper`), lifted with
// the callback and typed from the WIT in `encode`. The program's
// own signature was checked against the WIT when the wrapper
// was written.
if (e.callbackCoreName == "") {
throw new Error("The declared world exports '" + e.exportName +
"' as an async function, and the program's export is " +
"synchronous. Declare it `export async function " +
e.exportName + "(...)`.");
}
continue;
}
if (e.callbackCoreName != "") {
if (e.exportName == "main") {
// A program that blocks has its entry lifted async whatever
// the world says, because only a task the host lifted async
// may block; a synchronous declaration is satisfied by it,
// the value arriving through `task.return` as the host
// waits. Its result was typed from the program's own
// annotation (lib/component-entry.zena).
continue;
}
throw new Error("The program's '" + e.exportName + "' is async, " +
"and the declared world exports it as a synchronous function.");
}
if (e.witTyped) {
// A synchronous export richer than scalars and strings: the
// wrapper the compiler wrote marshals it, typed from the WIT.
continue;
}
this.#checkExportSignature(declared, e);
}
}
#checkExportSignature(declared: DeclaredExport, e: ComponentExportFunc): void {
let witFunc = declared.func;
let sig = e.signature;
if (witFunc.isAsync != sig.isAsync) {
throw new Error("The program and the WIT disagree about whether " +
"export '" + declared.name + "' is async" +
(if (sig.isAsync) {
" — a program that sleeps is entered through an async lift, " +
"so the world must declare `export " + declared.name +
": async func();`."
} else {
"."
}));
}
if (witFunc.params.length != sig.paramTypes.length) {
throw new Error("Export '" + declared.name + "': the WIT declares " +
i32ToString(witFunc.params.length) + " parameter(s) and the " +
"program's signature has " + i32ToString(sig.paramTypes.length) +
".");
}
for (var i = 0; i < witFunc.params.length; i += 1) {
let want = exportableWitOpcode(witFunc.params[i].type);
if (want < 0) {
throw new Error("Export '" + declared.name + "', parameter '" +
witFunc.params[i].name.name + "': the WIT type is not yet " +
"expressible by a program export — only flat scalars and " +
"string cross today.");
}
if (want != sig.paramTypes[i]) {
throw new Error("Export '" + declared.name + "', parameter '" +
witFunc.params[i].name.name + "': the WIT says '" +
witTypeName(witFunc.params[i].type) + "' and the program's " +
"signature says '" + scalarWitName(sig.paramTypes[i]) + "'.");
}
}
let witResult = witFunc.result;
if (witResult == null) {
if (sig.result != noComponentResult) {
throw new Error("Export '" + declared.name + "': the WIT declares " +
"no result and the program's signature returns '" +
scalarWitName(sig.result) + "'.");
}
return;
}
let want = exportableWitOpcode(witResult as Type);
if (want < 0) {
throw new Error("Export '" + declared.name + "': the WIT result " +
"type is not yet expressible by a program export — only flat " +
"scalars and string cross today.");
}
if (sig.result == noComponentResult) {
throw new Error("Export '" + declared.name + "': the WIT declares " +
"a '" + witTypeName(witResult as Type) + "' result and the " +
"program's signature returns nothing.");
}
if (want != sig.result) {
throw new Error("Export '" + declared.name + "': the WIT says '" +
witTypeName(witResult as Type) + "' and the program's " +
"signature says '" + scalarWitName(sig.result) + "'.");
}
}
}
/**
* The encoder as drivers inject it (`BinaryGenerator.importEncoder`) —
* the one edge from the compiler's build to the WIT parser. With no
* arguments, the derived-world default; with `--wit`'s document text
* (and `--world`'s name, or "" to take the document's sole world), the
* declared world becomes the authority and disagreements are errors.
*/
export function makeImportEncoder(
witSource: String | null = null,
worldName: String = "",
packagesWit: String = ""
): ImportTypeEncoder {
if (witSource == null) {
return new DerivedImportEncoder(packagesWit);
}
return new DeclaredWorldEncoder(witSource as String, worldName, packagesWit);
}
- 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 |
|
|