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

38.5 KiB Raw
/**
 * Compiling one source file to a module on disk: what `zc` does, as a
 * function other programs can call. The compiler's own command line
 * (`src/cli/main.zena`) and the `zena` command line both use it.
 *
 * It reads source and writes the module through `zena:fs`, so the caller
 * decides what it can reach through its preopens: the entry and its
 * package manifest are read relative to the working directory, and the
 * standard library from `stdlibRoot`.
 */

import { getEnv } from 'zena:cli';
import { ByteBuffer, StringBuilder } from 'zena:core';
import { JsonBuilder } from 'zena:json';
import { readFile, readFileBytes, writeFileBytes, writeFile, exists } from 'zena:fs';
import { CompilerHost } from './library-loader.zena';
import { PackageConfig, stdlibIdToRelativeFile } from './module-resolver.zena';
import { loadWorkspace } from './package-manifest.zena';
import {
  Compiler, CompilerOptions, ProgramCheckResult, createCompiler, CompileOptions,
  checkCompilation, withBuiltinPackages, buildStdlibConfig, setCheckAllBodies
} from './compiler.zena';
import { DiagnosticCode, DiagnosticSeverity, SourceSpan, SyntaxError } from './diagnostics.zena';
import { BinaryGenerator } from './codegen/binary-generator.zena';
import { WatGenerator } from './codegen/wat-generator.zena';
import { Program, CompilationUnit } from './program.zena';
import { Module } from './ast.zena';
import { nowMs, performance } from './time.zena';
import {
  defaultImportedStringConstants, defaultTarget, isKnownTarget,
  knownTargetsDescription, targetEmitsComponent, targetUsesJsStrings
} from './targets.zena';
import { compileComponentRuntimeModule } from './codegen/component-runtime.zena';
import { reportCensus } from './census.zena';
import { markTypes, setCensusEnabled } from './types.zena';
import { makeImportEncoder } from './codegen/wit-imports.zena';
import {
  isWitModulePath, synthesizeWitModule, synthesizeExportWrapper,
  declaredPackageNamespaces
} from './wit-module-synth.zena';
import { ComponentEntryWrapper } from './component-entry.zena';
import { readWitSource, readWitDocument } from './wit-source.zena';
import { WitDocument, witDiagnostic } from 'zena-lang:wit-parser/document';
import { parseSyntax } from 'zena-lang:wit-parser';
import { Ast as WitAst } from 'zena-lang:wit-parser/parser';
import { checkExtensionViews } from './extension-views.zena';
import { directoryNames } from './fs-host.zena';
import { HashMap } from 'zena:collections';

export { defaultTarget } from './targets.zena';

/**
 * "-O" levels: 0, 1, 2, and s (size — the loop with budgets down,
 * currently equal to 2). Returns -1 on anything else.
 */
export function parseOptLevel(text: String): i32 {
  if (text == "0") { return 0; }
  if (text == "1") { return 1; }
  if (text == "2") { return 2; }
  if (text == "s") { return 2; }
  return -1;
}

/** What `optLevel` means when a request leaves it out. */
export let defaultOptLevel = 1;

/** What to compile, where to put it, and how. */
export type CompileFileOptions = {
  /** The source file, relative to the working directory. */
  entry: String,
  /** Where to write the module; a `.wat` path writes the text form. */
  outPath: String,
  target?: String,
  /**
   * Compile a test suite: a file without its own `main` gets one that
   * runs `tests` through `zena:test`'s `runAndReport`.
   */
  testMode?: boolean,
  /** Print a report of how long each compiler phase took. */
  time?: boolean,
  /** A WIT file or directory declaring the component's world. */
  witPath?: String,
  /** Which world in `witPath`, when it declares several. */
  worldName?: String,
  /**
   * WIT files or directories the program's extensions are written to.
   * Each interface in them that `worldName` imports or exports must be
   * the program's view of it (`extension-views.zena`), or the compile
   * fails naming what differs.
   */
  extensionWitPaths?: Array<String>,
  /**
   * The module string literals are imported from on the `js` target:
   * the `importedStringConstants` the host compiles the module with.
   * `defaultImportedStringConstants` when absent; an error on any other
   * target.
   */
  importedStringConstants?: String,
  /**
   * Group imports by module, and by type within a module, in the
   * encodings of the compact import section proposal
   * (`ModuleGenerator.compactImports`). Only on a target that emits a
   * core module.
   */
  compactImports?: boolean,
  /** Emit a name section, so traps name functions. */
  debugNames?: boolean,
  warnUnnecessaryCasts?: boolean,
  /** 0, 1 or 2; see docs/design/optimization-pipeline.md. */
  optLevel?: i32,
  /** Where the standard library's `zena/` directory is. */
  stdlibRoot?: String,
  /**
   * The absolute path of the working directory, the workspace root. With
   * it, a path dependency outside the workspace (`../zena/packages/lib`)
   * is read by its absolute path; without it, or when it is empty, such a
   * dependency cannot be read.
   */
  projectRoot?: String,
  /**
   * Where fetched packages are, as `zena pkg fetch` stores them: each
   * package's source archive unpacked in `sources/<CID>`. Without it, or
   * when it is empty, the packages `zena-lock.json` pins are not
   * available.
   */
  packageCache?: String,
  /** Print "Compiling ..." and "Success: wrote ..." lines. */
  progress?: boolean,
  /**
   * Called with each source file's path just before the compiler reads
   * it, as the compiler names it: relative to the working directory, or
   * under `stdlibRoot`. A compile cache records these to know when its
   * entry is stale.
   */
  onRead?: (path: String) => void,
  /**
   * A component's runtime memory module, already compiled, as the path
   * to its `.wasm`. Absent or empty means compile one
   * (`component-runtime.zena`), as an empty `witPath` means no declared
   * world.
   *
   * Its bytes do not vary with the program — core module 0 has no
   * imports, and the program module imports its exports at the
   * component level — so a driver that can keep them between builds
   * should, because compiling them is about two thirds of a small
   * component build. A caller passing this is asserting the bytes were
   * built from the same standard library this compile is reading.
   */
  runtimeMemoryPath?: String,
};

/** The default `onRead`: a compile nothing is caching ignores it. */
function ignoreRead(path: String) {}

/**
 * The host the compiler reads source through: files from the working
 * directory, `zena:` modules from the standard library, and WIT-backed
 * modules synthesized from their WIT.
 */
class FileHost implements CompilerHost {
  testMode: boolean;
  stdlibRoot: String;
  onRead: (path: String) => void;
  /**
   * The entry of the compile in progress: in test mode, the one file
   * that gets a `main`.
   */
  var entryPath = "";
  /** The WIT-backed packages' source, once it has been read. */
  var packagesWit = "";
  new(this.testMode, this.stdlibRoot, this.onRead);

  /**
   * The file a module's source is read from, as `onRead` names it: a
   * `zena:` module is a file under the standard library's root.
   */
  fileOf(path: String): String {
    return if (path.startsWith("zena:")) {
      `${this.stdlibRoot}/${stdlibIdToRelativeFile(path)}`
    } else {
      path
    };
  }

  async readFile(path: String): Future<String> {
    // A WIT-backed package's module: no file exists — the source is
    // synthesized from the package's WIT.
    if (isWitModulePath(path)) {
      return await synthesizeWitModule(this, path, this.packagesWit);
    }
    let actualPath = this.fileOf(path);
    let onRead = this.onRead;
    onRead(actualPath);
    let content = await readFile(actualPath);
    if (this.testMode && path == this.entryPath) {
      // A file that declares its own entry point is left alone. This runs
      // before the source is parsed, so the test is textual; what matters is
      // that it be narrow enough not to fire on ordinary prose or data.
      //
      // It used to look for "let main", "main =" or "main(" anywhere in the
      // file, which matched far more than declarations: `let mainScope`, and
      // — inside a string literal — the `domain(` of a URL pattern. A suite
      // that merely mentioned one got no entry point and then failed with
      // "Failed to find `main` export", naming nothing in the file that
      // caused it. See tests/test/wrapper-main-substring_test.zena.
      if (content.contains("export let main ") ||
          content.contains("export let main=") ||
          content.contains("export function main(")) {
        return content;
      }
      // Asynchronous, because the runner awaits each test: a test's
      // body may be.
      return "import {runAndReport} from 'zena:test';\n" +
        content +
        "\nexport async function main(): Future<i32> {\n  return await runAndReport(tests, (s: String): void => {\n    console.log(s);\n  });\n}\n";
    }
    return content;
  }

  async listDir(path: String): Future<Array<String> | null> {
    return await directoryNames(path);
  }
}

// Load the packages of the workspace in the working directory, from its
// manifests (`loadWorkspace`). No workspace is
// fine — standalone files need only stdlib and relative imports — but a
// malformed one throws loudly, and so does one that pins a package the cache
// does not have.
async function loadPackages(
  host: CompilerHost,
  projectRoot: String | null,
  packageCache: String | null
): Future<HashMap<String, PackageConfig>> {
  let packages = await loadWorkspace(host, ".", projectRoot, packageCache);
  if (packageCache == null) {
    return packages;
  }
  for (let key in packages.keys()) {
    let config = packages[key];
    if (config.root.startsWith(`${packageCache}/`) && !(await exists(config.root))) {
      throw new Error(`${key} is not in the package cache (${config.root}). Run 'zena pkg fetch'.`);
    }
  }
  return packages;
}

// `loadPackages`, or null after printing why the workspace did not load.
// A manifest that cannot be read is a fault in the input, like a syntax
// error, and its message names the manifest. Thrown, it escaped
// `compileFile` before any of its handlers, so `zc` trapped with no
// message at all (https://github.com/elematic/zena/issues/534).
async function loadPackagesOrReport(
  host: CompilerHost,
  projectRoot: String | null,
  packageCache: String | null
): Future<HashMap<String, PackageConfig> | null> {
  try {
    return await loadPackages(host, projectRoot, packageCache);
  } catch (e) {
    console.error(`Error: ${e.message}`);
    return null;
  }
}

function reportDiagnosticLine(kind: String, file: String, line: i32, column: i32, message: String) {
  console.error(`${file}:${i32ToString(line)}:${i32ToString(column)} - ${kind}: ${message}`);
}

/**
 * Whether a warning is printed without `ZENA_WARN_UNNECESSARY_CASTS`: one
 * about what the program does, where the others are hints about what it
 * costs (casts, adaptations, boxing).
 */
function printsByDefault(code: DiagnosticCode) {
  return code == DiagnosticCode.DiscardedOwner;
}

/**
 * Reports a fault in the `--wit` document with its file, line, column
 * and an underline, the way a fault in a `.zena` file is reported, and
 * returns whether `e` was one — so a caller can go on to whatever else
 * `e` means.
 *
 * A malformed WIT document is a mistake in the input, so it is a
 * diagnostic and a status of 1. The parser signals it by throwing, and
 * letting that escape `compileFile` loses the position: `zena`
 * printed "the compiler failed on main.zena: expected identifier", and a
 * compiler running as a component printed nothing at all. See
 * https://github.com/elematic/zena/issues/158.
 */
function reportWitFailure(doc: WitDocument | null, e: Error): boolean {
  if (doc == null) {
    return false;
  }
  let text = witDiagnostic(doc as WitDocument, e);
  if (text == null) {
    return false;
  }
  console.error(text as String);
  return true;
}

/** `text` followed by spaces, up to `width` bytes. */
function padRight(text: String, width: i32) {
  let b = new StringBuilder();
  b.append(text);
  var i = text.length;
  while (i < width) {
    b.append(" ");
    i += 1;
  }
  return b.toString();
}

/** Spaces followed by `text`, up to `width` bytes. */
function padLeft(text: String, width: i32) {
  let b = new StringBuilder();
  var i = text.length;
  while (i < width) {
    b.append(" ");
    i += 1;
  }
  b.append(text);
  return b.toString();
}

/** Milliseconds to one decimal place. */
function ms1(value: f64) {
  return f64ToString(((value * 10.0) as i64 as f64) / 10.0);
}

/**
 * The longest phase name that is a proper prefix of `name` followed by
 * `-`, or null. `codegen-discovery-init` nests under
 * `codegen-discovery` rather than under `codegen`, so the longest
 * match wins.
 */
function parentPhaseOf(name: String, names: GrowableArray<String>) {
  var best: String | null = null;
  for (let candidate in names) {
    if (candidate.length >= name.length) {
      continue;
    }
    if (!name.startsWith(`${candidate}-`)) {
      continue;
    }
    let incumbent = best;
    if (incumbent == null || candidate.length > incumbent.length) {
      best = candidate;
    }
  }
  return best;
}

/**
 * The phase list as JSON, for a caller that is going to do arithmetic
 * on it. `ZENA_TIME_JSON=1` with `--time` prints this instead of the
 * table; an env var rather than a flag so that neither command line
 * has to carry it.
 *
 * One object per phase, in the order the compiler entered them, each
 * with its name, total milliseconds, how many times it was entered,
 * and the phase that contains it. Parsing the table instead would mean
 * a benchmark breaking whenever a column moved.
 */
function printTimingJson() {
  let phases = performance.phases();
  let names = new Array<String>(phases.length);
  for (let phase in phases) {
    names.push(phase.name);
  }
  let b = new JsonBuilder();
  b.beginObject();
  b.key("schemaVersion").i32(1);
  b.key("phases").beginArray();
  for (let phase in phases) {
    b.beginObject();
    b.key("name").string(phase.name);
    b.key("totalMs").f64(phase.total);
    b.key("count").i32(phase.count);
    b.key("parent");
    let parent = parentPhaseOf(phase.name, names);
    if (parent != null) { b.string(parent as String); } else { b.nullValue(); }
    b.endObject();
  }
  b.endArray();
  b.endObject();
  console.log(b.toString());
}

/**
 * Prints every phase `performance` measured, in the order the compiler
 * first entered each, nested under the phase whose name prefixes it.
 * The total is the sum of the top-level phases, which are the ones that
 * do not overlap.
 *
 * The report reads the phase list rather than naming phases itself, so
 * a `performance.start` added anywhere in the compiler appears here
 * without this function changing.
 */
function printTimingReport() {
  let phases = performance.phases();
  if (phases.length == 0) {
    return;
  }
  let names = new Array<String>(phases.length);
  for (let phase in phases) {
    names.push(phase.name);
  }

  console.log("");
  console.log("=== Compiler Timing Report ===");
  var total = 0.0;
  for (let phase in phases) {
    let parent = parentPhaseOf(phase.name, names);
    var depth = 0;
    var walk = parent;
    while (walk != null) {
      depth += 1;
      walk = parentPhaseOf(walk as String, names);
    }
    // A top-level phase is one no other phase contains, so these are
    // the ones that sum to the whole compile.
    let label = if (parent == null) {
      total = total + phase.total;
      phase.name
    } else {
      phase.name.sliceBytes((parent as String).length + 1, phase.name.length)
    };
    let indent = padRight("", depth * 2);
    let calls = if (phase.count == 1) { "" } else { ` (${i32ToString(phase.count)} calls)` };
    console.log(`${padRight(`${indent}${label}:`, 28)}${padLeft(ms1(phase.total), 9)} ms${calls}`);
  }
  console.log("------------------------------");
  console.log(`${padRight("Total:", 28)}${padLeft(ms1(total), 9)} ms`);
  console.log("==============================");
}

/**
 * Compiles `options.entry` and writes the module to `options.outPath`.
 * Returns 0 on success. On a mistake in the options or an error in the
 * program it prints the diagnostics to stderr and returns 1; it never
 * ends the process, so a caller can compile again.
 */
/**
 * How many compiles a session runs on one compiler before it starts a new
 * one. What a compiler accumulates per entry point (nominal types, model
 * nodes, instantiations interned on the standard library's own generic
 * types) is never released while it lives, so past a couple of dozen
 * entries it costs more than sharing the standard library saves. The
 * portable execution tests measured the whole saving by eight entries
 * and settled on 16; see "Portable Tests" in ../CONTEXT.md.
 */
let entriesPerCompiler = 16;

/**
 * Opens a session for compiles with `options`, or prints why it cannot
 * and returns null. `entry` and `outPath` are ignored: each compile names
 * its own. The workspace's manifests and the WIT-backed packages' source
 * are read here, once for every compile the session runs, and `onRead`
 * hears about them first.
 */
export async function openCompileSession(options: CompileFileOptions): Future<CompileSession | null> {
  // ZENA_CHECK_ALL_BODIES=1 checks every loaded module's bodies when
  // its module is checked, instead of leaving a dependency's for
  // reachability to ask for. See docs/design/lazy-body-checking.md.
  setCheckAllBodies(getEnv("ZENA_CHECK_ALL_BODIES") != null);
  // The census's distinct-substitution count keeps a set of keys, so
  // it is gathered only when the report is wanted.
  setCensusEnabled(getEnv("ZENA_CENSUS") != null);

  let {
    witPath = "",
    worldName = "",
    stdlibRoot = "/stdlib",
    projectRoot = "",
    packageCache = "",
    testMode = false,
    compactImports = false,
    warnUnnecessaryCasts = false,
  } = options;
  // Read with `??` rather than a destructuring default: a default in a
  // destructuring pattern does not see module-level bindings, and these
  // name theirs rather than writing it out.
  let target = options.target ?? defaultTarget;
  let onRead = options.onRead ?? ignoreRead;

  if (!isKnownTarget(target)) {
    console.error("Error: invalid target '" + target + "' (expected " +
        knownTargetsDescription() + ")");
    return null;
  }
  // A declared world (docs/design/component-emission.md, Part 3): the
  // WIT becomes the authority the program is compiled against, and
  // disagreements between it and the Zena are errors.
  if ((witPath != "" || worldName != "") && !targetEmitsComponent(target)) {
    console.error(
        "Error: --wit/--world declare a component's world, and the " +
        "target is '" + target + "'. Use --target component or --target zena-component.");
    return null;
  }
  if (worldName != "" && witPath == "") {
    console.error("Error: --world names a world in a --wit document, " +
        "and no --wit was given.");
    return null;
  }
  let extensionWits = new Array<String>();
  if (let {extensionWitPaths} = options) {
    for (let path in extensionWitPaths) {
      extensionWits.push(path);
    }
  }
  if (extensionWits.length > 0 && (witPath == "" || worldName == "")) {
    console.error("Error: --extension-wit checks the program's world against " +
        "its extensions' WIT, and no --wit and --world name that world.");
    return null;
  }
  if (let {importedStringConstants as given} = options) {
    if (given == "") {
      console.error("Error: --imported-string-constants names a module, " +
          "and the name is empty.");
      return null;
    }
    if (!targetUsesJsStrings(target)) {
      console.error(
          "Error: --imported-string-constants names the module string " +
          "literals are imported from, and the target is '" + target +
          "', which imports none. Use --target js or --target zena-js.");
      return null;
    }
  }
  if (compactImports && targetEmitsComponent(target)) {
    console.error("Error: --compact-imports writes a core module's imports " +
        `in an encoding wasmtime does not read, and the target is '${target}', ` +
        "which emits a component.");
    return null;
  }

  let host = new FileHost(testMode, stdlibRoot, onRead);
  // The declared world's WIT: one file, or a directory whose *.wit
  // files are concatenated in name order into one document.
  var witSource = "";
  // Kept so a failure anywhere in the compile can be pinned to the file
  // and line it came from; the parser only knows offsets into the
  // joined document.
  var witDoc: WitDocument | null = null;
  if (witPath != "") {
    if (!(await exists(witPath))) {
      console.error("Error: --wit path does not exist: " + witPath);
      return null;
    }
    let doc = await readWitDocument(host, witPath);
    witDoc = doc;
    witSource = doc.source;
  }
  // The program's views of its extensions' interfaces, against the
  // extensions' own WIT: a problem is reported here, naming the
  // interface, before the program is checked against the world.
  if (extensionWits.length > 0) {
    var hostAst: WitAst | null = null;
    try {
      hostAst = parseSyntax(witSource);
    } catch (e) {
      if (e is Error && reportWitFailure(witDoc, e)) {
        return null;
      }
      throw e;
    }
    var problems = 0;
    for (let path in extensionWits) {
      if (!(await exists(path))) {
        console.error("Error: --extension-wit path does not exist: " + path);
        return null;
      }
      let guestDoc = await readWitDocument(host, path);
      var guestAst: WitAst | null = null;
      try {
        guestAst = parseSyntax(guestDoc.source);
      } catch (e) {
        if (e is Error) {
          let where = witDiagnostic(guestDoc, e) ?? e.message;
          console.error(`Error: ${where}`);
          return null;
        }
        throw e;
      }
      for (let problem in checkExtensionViews(hostAst as WitAst, worldName,
          guestAst as WitAst, path)) {
        console.error(`Error: ${problem}`);
        problems += 1;
      }
    }
    if (problems > 0) {
      return null;
    }
  }
  let loaded = await loadPackagesOrReport(host, if (projectRoot == "") null else projectRoot,
      if (packageCache == "") null else packageCache);
  if (loaded == null) {
    return null;
  }
  let packages = loaded as HashMap<String, PackageConfig>;
  // A declared world's document answers for its own packages: the
  // program imports the world's interfaces by name (`test:app/oracle`
  // for a document declaring `package test:app`), and the resolver
  // maps the namespace to a WIT-backed package rooted at the document.
  // A namespace the manifest or the stdlib already provides keeps its
  // package — a document vendoring `wasi:clocks` does not take over
  // `wasi` — and its interfaces are reached as before.
  if (witSource != "") {
    // The first thing that parses the document, so a malformed one is
    // reported here rather than from deeper in the compile.
    try {
      for (let namespace in declaredPackageNamespaces(witSource)) {
        if (namespace == "wasi" || namespace == "zena" || packages.has(namespace)) { continue; }
        let declared = new PackageConfig("", null);
        declared.witRoot = witPath;
        packages[namespace] = declared;
      }
    } catch (e) {
      if (e is Error && reportWitFailure(witDoc, e)) {
        return null;
      }
      throw e;
    }
  }
  // The WIT-backed packages' real source, so the encoder emits their
  // interfaces' true types rather than deriving them from the
  // synthesized declarations (which are flattened core shapes), and so
  // a declared world can import their interfaces by name. Name-sorted:
  // a HashMap iterates in uid order, which depends on what the process
  // did earlier, and emitted bytes must not.
  var packagesWit = "";
  if (targetEmitsComponent(target)) {
    // Including the packages the stdlib carries (`wasi` and `zena:host`),
    // the same set the resolver sees.
    let allPackages = withBuiltinPackages(stdlibRoot, packages);
    allPackages["zena"] = buildStdlibConfig(stdlibRoot);
    let witPackages = new Array<String>();
    let packageNames = allPackages.keys();
    for (let packageName in packageNames) {
      let root = allPackages[packageName].witRoot;
      // The declared document is the world's own source, parsed
      // alongside these; it does not ride along a second time.
      if (root != null && (root as String) != witPath) {
        witPackages.push(packageName);
      }
    }
    let byteLess = (x: String, y: String) => {
      var minLen = x.length;
      if (y.length < minLen) { minLen = y.length; }
      for (var i = 0; i < minLen; i += 1) {
        let d = x.getByteAt(i) - y.getByteAt(i);
        if (d != 0) { return d < 0; }
      }
      return x.length < y.length;
    };
    for (var a = 0; a < witPackages.length; a += 1) {
      for (var b = a + 1; b < witPackages.length; b += 1) {
        if (byteLess(witPackages[b], witPackages[a])) {
          let t = witPackages[a];
          witPackages[a] = witPackages[b];
          witPackages[b] = t;
        }
      }
    }
    for (let packageName in witPackages) {
      packagesWit = packagesWit +
          (await readWitSource(host, allPackages[packageName].witRoot as String)) + "\n";
    }
    host.packagesWit = packagesWit;
  }
  return new CompileSession(
      options, host, {stdlibRoot, packages, warnUnnecessaryCasts}, witSource, witDoc);
}

/**
 * Compiles entry points one after another on one compiler, so what they
 * share, the standard library and the packages they import, is loaded,
 * parsed and checked once: each compile carries the previous one's check
 * forward for every file whose source has not changed. What every compile
 * needs is read once, by `openCompileSession`; the runtime memory module a
 * component embeds is built by the first compile that needs it.
 *
 * Every option but `entry` and `outPath` belongs to the session, and
 * `compile` takes those two. `compileFile` is a session of one compile.
 */
export final class CompileSession {
  #options: CompileFileOptions;
  #host: FileHost;
  #compilerOptions: CompilerOptions;
  var #compiler: Compiler;
  #witSource: String;
  #witDoc: WitDocument | null;
  var #previous: ProgramCheckResult | null = null;
  var #compiles = 0;
  var #runtimeMemory: ByteBuffer | null = null;
  var #sources = new GrowableArray<String>();

  new(
    options: CompileFileOptions,
    host: FileHost,
    compilerOptions: CompilerOptions,
    witSource: String,
    witDoc: WitDocument | null
  ) : #options = options,
      #host = host,
      #compilerOptions = compilerOptions,
      #compiler = createCompiler(host, compilerOptions),
      #witSource = witSource,
      #witDoc = witDoc;

  /**
   * The files the last compile's program is made of, as `onRead` names
   * them: its entry and everything that reaches, the standard library
   * included, whether this compile read them or an earlier one did.
   * WIT-backed modules have no file; their WIT is read when the session
   * opens. Empty when the last compile failed before it had a program.
   */
  sources: GrowableArray<String> {
    get { return this.#sources; }
  }

  /** The runtime memory module, built or read on first use. */
  async #runtimeMemoryModule(compiler: Compiler, stdlibRoot: String, runtimeMemoryPath: String): Future<ByteBuffer> {
    let built = this.#runtimeMemory;
    if (built != null) {
      return built as ByteBuffer;
    }
    let module = if (runtimeMemoryPath == "") {
      await compileComponentRuntimeModule(compiler, stdlibRoot)
    } else {
      // Already built, by a driver that keeps them between builds.
      new ByteBuffer().writeBytes((await readFileBytes(runtimeMemoryPath)) as ByteArray)
    };
    this.#runtimeMemory = module;
    return module;
  }

  /**
   * Compiles `entry`, a source file relative to the working directory,
   * and writes its module to `outPath`. Returns 0, or 1 after printing the
   * diagnostics.
   */
  async compile(entry: String, outPath: String): Future<i32> {
    let options = this.#options;
    let {
      stdlibRoot = "/stdlib",
      testMode = false,
      time = false,
      debugNames = false,
      compactImports = false,
      warnUnnecessaryCasts = false,
      progress = false,
      witPath = "",
      worldName = "",
    } = options;
    let target = options.target ?? defaultTarget;
    let runtimeMemoryPath = options.runtimeMemoryPath ?? "";
    let optLevel = options.optLevel ?? defaultOptLevel;
    let importedStringConstants =
        options.importedStringConstants ?? defaultImportedStringConstants;
    let filename = entry;
    let witSource = this.#witSource;
    let witDoc = this.#witDoc;

    if (this.#compiles == entriesPerCompiler) {
      // Nothing to release selectively: the instantiations a compile
      // adds are interned on the standard library's own types, so the
      // shared part is what grows. Replacing the compiler is the disposal.
      this.#compiler = createCompiler(this.#host, this.#compilerOptions);
      this.#previous = null;
      this.#compiles = 0;
    }
    this.#compiles += 1;
    this.#sources = new GrowableArray<String>();
    let compiler = this.#compiler;
    let host = this.#host;
    host.entryPath = filename;
    if (testMode) {
      // Test mode gives the entry a `main`, so its source as an entry
      // differs from its source as another file's import. Dropping it from
      // the compiler's cache before and after keeps either version from
      // serving a compile it does not belong to.
      compiler.delete(filename);
    }

    // Against a declared world the entry wrapper also implements the
    // world's async exports, which takes the WIT the compiler itself does
    // not link. Without a declared world the compiler writes its own.
    let declaredWit = witSource;
    let declaredWorld = worldName;
    let declaredPackages = host.packagesWit;
    let compileOptions: CompileOptions = if (witSource == "") {
      {entry: filename, target}
    } else {
      {
        entry: filename,
        target,
        componentWrapperSynth:
            (entryPath: String, ast: Module) =>
                synthesizeExportWrapper(declaredWit, declaredWorld, entryPath,
                    ast, declaredPackages),
      }
    };

    if (progress) {
      console.log(`Compiling ${filename}...`);
    }
    try {
      let compResult = await compiler.compile(compileOptions);
      let sources = new GrowableArray<String>();
      for (let file in compResult.files) {
        if (!isWitModulePath(file.path)) {
          sources.push(host.fileOf(file.path));
        }
      }
      this.#sources = sources;

      let checkResults = checkCompilation(compResult, this.#previous);
      this.#previous = checkResults;
      let {diagnostics} = checkResults;
      var hasError = false;
      for (let diag in diagnostics) {
        if (diag.severity == DiagnosticSeverity.Error) {
          if (diag.location != null) {
            let loc = diag.location as SourceSpan;
            reportDiagnosticLine("Error", loc.file, loc.line, loc.column, diag.message);
          } else {
            console.error("Error: " + diag.message);
          }
          hasError = true;
        } else if (diag.severity == DiagnosticSeverity.Warning &&
            (warnUnnecessaryCasts || printsByDefault(diag.code))) {
          if (diag.location != null) {
            let loc = diag.location as SourceSpan;
            reportDiagnosticLine("Warning", loc.file, loc.line, loc.column, diag.message);
          } else {
            console.error("Warning: " + diag.message);
          }
        }
      }

      if (hasError) {
        return 1;
      }

      checkResults.results[filename].model;
      let entryAst = compResult.entry.ast;
      let units = new Array<CompilationUnit>();
      var entryUnit: CompilationUnit | null = null;
      for (let file in compResult.files) {
        let res = checkResults.results[file.path];
        if (res != null) {
          let unit = {ast: file.ast, model: res.model};
          units.push(unit);
          if (file.ast.path == entryAst.path) {
            entryUnit = unit;
          }
        }
      }
      markTypes("check");
      let tCodegen = performance.start("codegen");
      let program = new Program(units, entryUnit);

      // Every compile goes AST -> ZIR -> wasm; a lowering bail is a
      // fatal error. ZENA_ZIR_STATS=1 prints the lowered count.
      let zirStats = getEnv("ZENA_ZIR_STATS") != null;

      // ZENA_WIDE_ARITHMETIC=1 emits the wide-arithmetic proposal's
      // instructions instead of the sequences that mean the same thing.
      // Opt-in because V8 does not implement the proposal yet.
      let wideArithmetic = getEnv("ZENA_WIDE_ARITHMETIC") != null;

      // Template lowering (docs/design/template-zir.md) is on unless
      // ZENA_TEMPLATES=0; ZENA_TEMPLATE_CHECK=1 lowers every templated
      // body directly too and fails on any difference.
      let templatesEnv = getEnv("ZENA_TEMPLATES");
      let templates = templatesEnv == null || templatesEnv as String != "0";
      let templateCheck = getEnv("ZENA_TEMPLATE_CHECK") != null;

      // `-o out.wat` emits the WAT text directly — the readable form of
      // exactly what the binary build would contain, for inspecting a
      // program's emitted shape (`zena build hello.zena -o hello.wat`).
      // `debug` contract clauses are compiled for a test build and for a
      // debug build (`-g`), and left out of every other
      // (docs/design/contracts.md).
      let debugContracts = testMode || debugNames;

      if (outPath.endsWith(".wat")) {
        let watOnly = new WatGenerator(target, zirStats, optLevel);
        watOnly.wideArithmetic = wideArithmetic;
        watOnly.debugContracts = debugContracts;
        watOnly.importedStringConstants = importedStringConstants;
        watOnly.compactImports = compactImports;
        watOnly.templates = templates;
        watOnly.templateCheck = templateCheck;
        watOnly.interner = checkResults.sharedState.interner;
        await writeFile(outPath, watOnly.generate(program));
        performance.end(tCodegen);
        if (progress) {
          console.log("Success: wrote " + outPath);
        }
        return 0;
      }

      let generator = new BinaryGenerator(target, zirStats, debugNames, optLevel);
      generator.wideArithmetic = wideArithmetic;
      generator.debugContracts = debugContracts;
      generator.importedStringConstants = importedStringConstants;
      generator.compactImports = compactImports;
      generator.templates = templates;
      generator.templateCheck = templateCheck;
      generator.propagate = getEnv("ZENA_PROPAGATE") != "0";
      // Codegen builds its unions through the checker's interner, so a
      // union means one object across the whole compile.
      generator.interner = checkResults.sharedState.interner;
      if (targetEmitsComponent(target)) {
        // The component's second core module, owning linear memory and
        // the allocator. Compiled up front — whether the program needs it
        // is only known after its own compile, and this one is small.
        //
        // The module emits few bytes and still costs a whole compile, with
        // its own load, parse, scope and check of the standard library it
        // draws on, which land in the same phase totals as the program's
        // own. Timed separately so the report says how much of a component
        // build is this module.
        let tRuntimeModule = nowMs();
        // Suspended: this is a compile of its own, and its load, parse,
        // scope and check would otherwise be added to this program's,
        // which made the report's total exceed wall-clock time by the
        // whole nested compile.
        performance.suspend();
        generator.runtimeMemoryModule =
            await this.#runtimeMemoryModule(compiler, stdlibRoot, runtimeMemoryPath);
        performance.resume();
        performance.add("codegen-runtime-module", nowMs() - tRuntimeModule);
        // A declared world compiles against its own document, with the
        // WIT-backed packages spliced in so it can import their
        // interfaces by name; without one, each interface's WIT is
        // derived from the program, except for the packages' own.
        generator.importEncoder = if (witPath != "") {
          makeImportEncoder(witSource, worldName, host.packagesWit)
        } else {
          makeImportEncoder(null, "", host.packagesWit)
        };
      }
      let wasmBytes = generator.generate(program).toByteArray();
      markTypes("emit");
      await writeFileBytes(outPath, wasmBytes as FixedArray<u8>);

      // The WAT dump runs a SECOND full generator pass and its text
      // dwarfs the binary (~30x — the tests module's dump is ~135 MB),
      // so it is opt-in for debugging.
      if (getEnv("ZENA_EMIT_WAT") != null) {
        let watGenerator = new WatGenerator(target, false, optLevel);
        watGenerator.debugContracts = debugContracts;
        watGenerator.importedStringConstants = importedStringConstants;
        watGenerator.compactImports = compactImports;
        let watString = watGenerator.generate(program);
        await writeFile(outPath + ".wat", watString);
      }
      performance.end(tCodegen);

      if (progress) {
        console.log("Success: wrote " + outPath);
      }

      // ZENA_CENSUS=1 prints what the compile retained, by object kind
      // (census.zena). After codegen, so the type-key counters have
      // everything the generator interned.
      if (getEnv("ZENA_CENSUS") != null) {
        reportCensus(program);
      }

      if (time) {
        if (getEnv("ZENA_TIME_JSON") != null) {
          printTimingJson();
        } else {
          printTimingReport();
        }
      }
    } catch (e) {
      // A syntax error is a fault in the input, and the parser has already
      // formatted it with its file, line, column and an underline. Report
      // it the way a type error is reported and fail: the banner and the
      // wasm backtrace below are for a fault in the compiler itself, and
      // printing them here says the wrong thing about whose bug it is.
      if (e is SyntaxError) {
        console.error(e.message);
        return 1;
      }
      // The same for a fault in the declared world's WIT, which the
      // encoder and the wrapper synthesizer reach only here.
      if (e is Error && reportWitFailure(witDoc, e)) {
        return 1;
      }
      console.log("Exception caught in CLI compiler!");
      if (e is Error) {
        console.log("Error message: " + e.message);
        let stack = e.getStackTrace();
        if (stack != null) {
          console.log("Stack Trace: \n" + stack);
        }
      }
      throw e;
    } finally {
      if (testMode) {
        compiler.delete(filename);
      }
    }

    return 0;
  }
}

export async function compileFile(options: CompileFileOptions): Future<i32> {
  let session = await openCompileSession(options);
  if (session == null) {
    return 1;
  }
  return await session.compile(options.entry, options.outPath);
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19