compiler 0.0.2-preview.1

The Zena self-hosted compiler

Readme Files Dependencies Versions

compiler#

The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).

Usage#

Parsing a Single File#

Use compiler/parser to parse Zena source text into an AST (Module):

import { parse } from 'compiler/parser';

let ast = parse('export let answer = 42;', 'example.zena');

Loading and Checking a Program#

Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:

import {
  createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';

let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
  stdlibRoot,
  packages,
});

let result = await compiler.compile({
  entry: '/workspace/main.zena',
  target: 'host',
});
let checked = checkCompilation(result);

Compiling a File to WebAssembly#

Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:

import { compileFile } from 'compiler/compile-file';

let ok = await compileFile({
  entry: 'src/main.zena',
  outPath: 'out/main.wasm',
  stdlibRoot: '/stdlib',
});

Libraries#

  • compiler / compiler/compiler — compiler entry point (Compiler, createCompiler, checkCompilation, ProgramCheckResult)
  • compiler/compile-file — end-to-end file compilation (compileFile, CompileFileOptions)
  • compiler/tokenizer — lexer and token definitions (tokenize, Token, TokenType)
  • compiler/parser — recursive-descent parser (parse, Parser)
  • compiler/ast — AST node definitions (Node, Module, Statement, Expression, TypeAnnotation)
  • compiler/visitor — AST traversal helpers (walk, Visitor)
  • compiler/scope — lexical scope and symbol resolution (ScopeBuilder, ScopeResult, Symbol)
  • compiler/checker — static type checker (checkModule, CheckResult)
  • compiler/semantic-model — semantic queries over a checked module (SemanticModel)
  • compiler/types — compiler type representations (Type, ClassType, FunctionType, typeToString)
  • compiler/diagnostics — compiler diagnostics and source spans (Diagnostic, DiagnosticCode, DiagnosticSeverity, SourceSpan)
  • compiler/package-manifest — zena-package.json manifest and workspace loader (loadWorkspace, loadPackageMap)
  • compiler/module-resolver — package and relative module specifier resolution (ModuleResolver, PackageConfig)
  • compiler/library-loader — module graph loader (LibraryLoader, CompilerHost, SourceFile)
  • compiler/codegen/binary-generator — WebAssembly GC binary emitter (BinaryGenerator)
  • compiler/codegen/wat-generator — WebAssembly Text (WAT) emitter (WatGenerator)

License#

MIT

14.3 KiB Raw
/**
 * @file
 *
 * The component target's entry wrapper: a module the compiler writes
 * beside the entry, for the functions whose values reach the host
 * through a typed `task.return`.
 *
 * A callback-lifted export hands its result to the host through
 * `task.return`, a canonical builtin whose canon entry carries the
 * result's type. The core function that calls it has to be declared
 * at that type, and nothing in the standard library can name what a
 * particular program's functions return. So the declarations are
 * written here, per program, into a small module loaded beside the
 * entry. The module imports the program's functions, declares
 * `task.return` at each one's result type, and exports a wrapper per
 * function that starts it and hands its future to the driver together
 * with the typed return to call once the future settles. The entry
 * adapter (`codegen/ir/component-adapters.zena`) calls a wrapper in
 * place of the function.
 *
 * This file writes the wrapper for `main` when its value needs one: an
 * async `main` returning a flat scalar or a `String`, and a synchronous
 * `main` returning a `String`, which the entry cannot return itself
 * because a `string` result is read out of linear memory. The choice
 * is made from the entry's syntax alone, the annotation on `main`, so
 * the wrapper can be loaded in the same compile as the entry, before
 * anything is checked. A declared world's async exports need the WIT,
 * which the compiler does not link: `wit-module-synth.zena` writes
 * those wrappers, with the same shape, and the driver injects it
 * (`CompilerOptions.componentWrapperSynth`).
 *
 * See docs/design/component-async-exports.md.
 */

import { StringBuilder, join } from 'zena:core';
import {
  Module, FunctionDeclaration, VariableDeclaration, FunctionExpression,
  IdentifierPattern, NamedTypeAnnotation, ClassDeclaration, MethodDefinition,
  Identifier
} from './ast.zena';
import { toKebabName } from './codegen/component-emitter.zena';

/** What the wrapper's path adds to the entry's. */
let wrapperSuffix = '.component-entry.zena';

/** Whether `path` names a wrapper this module wrote. */
export function isComponentEntryPath(path: String): boolean {
  return path.endsWith(wrapperSuffix);
}

/** The wrapper's path for the entry at `entryPath`. */
export function componentEntryPathFor(entryPath: String): String {
  return entryPath + wrapperSuffix;
}

/** The core function name the adapter looks for in the wrapper. */
export let componentEntryRunName = 'run';

/**
 * What a wrapper adds to a world export's name to name the function
 * the adapter calls: `describe` is implemented by `describe_export`.
 * WIT names are kebab-case, so no camelCase rendering of one contains
 * an underscore and the suffix cannot collide.
 */
export let componentExportSuffix = '_export';
/**
 * The component export name a wrapper's base name stands for. A plain
 * name is the kebab-case of the Zena spelling (`describe`). A
 * resource's function carries the resource and the kind in the base,
 * joined by double underscores (no WIT-derived name contains one):
 * `surface__constructor`, `surface__method__onFrame` and
 * `surface__static__create` name the canonical ABI's
 * `[constructor]surface`, `[method]surface.on-frame` and
 * `[static]surface.create`. The empty string for a base with no
 * kebab-case rendering.
 */
export function componentExportNameOf(base: String): String {
  let parts = base.split('__');
  if (parts.length == 1) {
    return toKebabName(base);
  }
  let resource = toKebabName(parts[0]);
  if (resource == '') {
    return '';
  }
  if (parts.length == 2 && parts[1] == 'constructor') {
    return '[constructor]' + resource;
  }
  if (parts.length == 3 && (parts[1] == 'method' || parts[1] == 'static')) {
    let member = toKebabName(parts[2]);
    if (member == '') {
      return '';
    }
    return `[${parts[1]}]${resource}.${member}`;
  }
  return '';
}

/** The wrapper base name for a resource's function: see
 * `componentExportNameOf`. */
export function resourceWrapperBase(resource: String, kind: String,
    member: String): String {
  if (kind == 'constructor') {
    return resource + '__constructor';
  }
  return `${resource}__${kind}__${member}`;
}

/**
 * The suffix of a declared world's synchronous export wrapper — one
 * whose parameters or result are richer than the flat scalars and
 * strings a program export lifts on its own. Lifted directly, no
 * callback: the value comes back from the call, through a return
 * area when it flattens past one core value.
 */
export let componentSyncExportSuffix = '_export_sync';

/**
 * A wrapper to load beside the entry. `entrySpecifier` is how the
 * wrapper's source imports the entry, and `entryPath` is the loaded
 * entry's path, which the loader pins that specifier to so the entry
 * is not loaded a second time under a differently spelled path.
 */
export final class ComponentEntryWrapper {
  path: String;
  source: String;
  entrySpecifier: String;
  entryPath: String;
  new(this.path, this.source, this.entrySpecifier, this.entryPath);
}

/**
 * The flat scalar types a `main` may return through the wrapper:
 * the ones that lift as one core value, and that a synthesized module
 * can name without importing anything.
 */
let scalarResults = [
  'bool', 'i8', 'u8', 'i16', 'u16', 'i32', 'u32', 'i64', 'u64',
  'f32', 'f64'
];

function isScalarResult(name: String): boolean {
  for (let s in scalarResults) {
    if (s == name) { return true; }
  }
  return false;
}

/**
 * The result `main` returns through the wrapper, as the wrapper spells
 * its type: a flat scalar's name, `String`, or the empty string when
 * `main` needs no wrapper.
 *
 * An async `main` annotated `Future<T>` needs one for a flat scalar or
 * a `String` `T`. A synchronous `main` needs one only for `String`: a
 * scalar is known when it returns, and the entry adapter returns it
 * itself (ir/component-adapters.zena).
 */
function wrapperResultOf(func: FunctionExpression) {
  let annotation = func.returnType;
  if (!(annotation is NamedTypeAnnotation)) { return ''; }
  if (!func.isAsync) {
    return if (isStringResult(annotation)) 'String' else '';
  }
  if (annotation.name == 'Future') {
    let args = annotation.typeArguments;
    if (args != null) {
      if (args.length == 1) {
        let arg = args[0];
        if (arg is NamedTypeAnnotation) {
          if (isStringResult(arg)) {
            return 'String';
          }
          if (arg.typeArguments == null) {
            if (isScalarResult(arg.name)) {
              return arg.name;
            }
          }
        }
      }
    }
  }
  return '';
}

/** Whether `annotation` is `String`. */
function isStringResult(annotation: NamedTypeAnnotation) {
  return annotation.name == 'String' && annotation.typeArguments == null;
}

/**
 * The result the module's exported `main` returns through the wrapper,
 * or the empty string: see `wrapperResultOf`. Both spellings count:
 * `export async function main()` and `export let main = async () => ...`.
 */
export function mainWrapperResultOf(ast: Module): String {
  let main = exportedMainOf(ast);
  return if (main == null) '' else wrapperResultOf(main as FunctionExpression);
}

/** Whether the module exports an async `main`: the entry the
 * component lifts on its own, whichever way a declared world spells
 * it. */
export function hasAsyncMain(ast: Module): boolean {
  let main = exportedMainOf(ast);
  return main != null && (main as FunctionExpression).isAsync;
}

/**
 * Whether the entry's implementation of an export is `async`: the
 * function `name` at the top level, in either spelling, or, with
 * `className`, the method or static `member` of that class. False
 * when there is no such function, which the compile reports in its
 * own words. The wrapper for an export that returns nothing asks, to
 * hand an async implementation's future to the driver and to call a
 * synchronous one outright.
 */
export function exportedFunctionIsAsync(ast: Module, name: String,
    className: String, member: String): boolean {
  for (let stmt in ast.body) {
    if (className == '') {
      if (stmt is FunctionDeclaration) {
        if (stmt.name.name == name) {
          return stmt.func.isAsync;
        }
      } else if (stmt is VariableDeclaration) {
        let pattern = stmt.pattern;
        if (pattern is IdentifierPattern) {
          if (pattern.name == name) {
            let init = stmt.init;
            if (init is FunctionExpression) {
              return init.isAsync;
            }
          }
        }
      }
    } else if (stmt is ClassDeclaration) {
      if (stmt.name.name == className) {
        for (let m in stmt.body) {
          if (m is MethodDefinition) {
            let mname = m.name;
            if (mname is Identifier) {
              if (mname.name == member) {
                return m.isAsync;
              }
            }
          }
        }
      }
    }
  }
  return false;
}

/**
 * Whether the entry declares class `className` with a static `member`.
 * The wrapper for a plugin kind's `create` asks, to write the static
 * itself when the class leaves it out.
 */
export function classHasStatic(ast: Module, className: String, member: String): boolean {
  for (let stmt in ast.body) {
    if (stmt is ClassDeclaration) {
      if (stmt.name.name == className) {
        for (let m in stmt.body) {
          if (m is MethodDefinition) {
            let mname = m.name;
            if (mname is Identifier) {
              if (mname.name == member && m.isStatic) {
                return true;
              }
            }
          }
        }
      }
    }
  }
  return false;
}

/** The module's exported `main` function, in either spelling, or
 * null. */
function exportedMainOf(ast: Module): FunctionExpression | null {
  for (let stmt in ast.body) {
    if (stmt is FunctionDeclaration) {
      if (stmt.exported) {
        if (stmt.name.name == 'main') {
          return stmt.func;
        }
      }
    } else if (stmt is VariableDeclaration) {
      if (stmt.exported) {
        let pattern = stmt.pattern;
        if (pattern is IdentifierPattern) {
          if (pattern.name == 'main') {
            let init = stmt.init;
            if (init is FunctionExpression) {
              return init;
            }
          }
        }
      }
    }
  }
  return null;
}

/** The last path segment. */
function baseName(path: String) {
  var from = 0;
  for (var i = 0; i < path.length; i += 1) {
    if (path.getByteAt(i) == 47) { from = i + 1; } // '/'
  }
  return path.sliceBytes(from, path.length);
}

/** How a wrapper beside the entry imports it. */
export function componentEntrySpecifierFor(entryPath: String): String {
  return './' + baseName(entryPath);
}

/** The comment every wrapper opens with. */
export function renderWrapperHeader(sb: StringBuilder): void {
  sb.append('// Written by the compiler for the component target: the ');
  sb.append('wrappers whose\n');
  sb.append('// values reach the host through a typed `task.return`, ');
  sb.append('declared here at\n');
  sb.append('// each one\'s result type and called once its future ');
  sb.append('settles. See\n');
  sb.append('// docs/design/component-async-exports.md.\n');
}

/**
 * The names a main wrapper for `result` imports from `zena:wasi`.
 * `finishTask` hands an async main's value to the driver; a `String`
 * is staged into linear memory for the typed return to read, and a
 * synchronous main's wrapper tells the driver it has returned.
 */
export function mainWrapperAbiImports(result: String, isAsync: boolean): GrowableArray<String> {
  let names = new Array<String>();
  if (isAsync) {
    names.push('finishTask');
  }
  if (result == 'String') {
    names.push('stagedMark');
    names.push('stageString');
    names.push('releaseStagedFrom');
    if (!isAsync) {
      names.push('markReturned');
    }
  }
  return names;
}

/**
 * The typed return for `main`'s `result`, and `run`, which calls main
 * and returns its value: through the driver for an async main, once
 * the future settles, and at once for a synchronous one. Appended to a
 * wrapper whose imports already bring in `main` and the names
 * `mainWrapperAbiImports` lists.
 *
 * A scalar's `task.return` takes the value. A `String`'s is typed by
 * the WIT `string`, so its parameters are the staged bytes' address and
 * length, and the staging is freed once the return has read it.
 */
export function renderMainWrapper(sb: StringBuilder, result: String,
    isAsync: boolean): void {
  let isString = result == 'String';
  if (isString) {
    sb.append('@external("canon", "task.return#main", "return:#string")\n');
    sb.append('declare function taskReturnMain(ptr: i32, len: i32): void;\n\n');
    sb.append('function returnMain(value: String): void {\n');
    sb.append('  let mark = stagedMark();\n');
    sb.append('  let (ptr, len) = stageString(value);\n');
    sb.append('  taskReturnMain(ptr, len);\n');
    sb.append('  releaseStagedFrom(mark);\n');
    sb.append('}\n\n');
  } else {
    sb.append('@external("canon", "task.return#main")\n');
    sb.append('declare function taskReturnMain(value: ').append(result)
        .append('): void;\n\n');
  }
  let returnFn = if (isString) 'returnMain' else 'taskReturnMain';
  sb.append('export function ').append(componentEntryRunName)
      .append('(): void {\n');
  if (isAsync) {
    sb.append('  finishTask<').append(result).append('>(main(), (value: ')
        .append(result).append('): void => {\n');
    sb.append('    ').append(returnFn).append('(value);\n');
    sb.append('  });\n');
  } else {
    sb.append('  ').append(returnFn).append('(main());\n');
    sb.append('  markReturned();\n');
  }
  sb.append('}\n');
}

/**
 * The wrapper for the entry at `entryPath` with syntax `ast`, or null
 * when the program's `main` is synchronous, returns nothing or
 * returns something other than a flat scalar.
 */
export function componentEntryWrapperFor(
  entryPath: String,
  ast: Module
): ComponentEntryWrapper | null {
  let result = mainWrapperResultOf(ast);
  if (result == '') {
    return null;
  }
  let isAsync = hasAsyncMain(ast);
  let specifier = componentEntrySpecifierFor(entryPath);
  let sb = new StringBuilder();
  renderWrapperHeader(sb);
  sb.append('import { main } from \'').append(specifier).append('\';\n');
  sb.append('import { ');
  sb.append(join(mainWrapperAbiImports(result, isAsync), ', '));
  sb.append(' } from \'zena:wasi\';\n\n');
  renderMainWrapper(sb, result, isAsync);
  return new ComponentEntryWrapper(componentEntryPathFor(entryPath),
      sb.toString(), specifier, entryPath);
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19