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

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