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

21.5 KiB Raw
// Module resolution for the Zena compiler.
//
// Resolves import specifiers to canonical module paths. Handles:
// - Relative imports (./foo, ../bar)
// - Package imports (package:module)
// - Virtual modules (target-conditional resolution)
// - Internal modules (package-private)
//
// Resolution is a pure function of configuration (packages + target).
// No I/O is performed.

import { HashMap } from 'zena:collections';


// ============================================================================
// Package Configuration
// ============================================================================

// Configuration for a single module export within a package.
// For simple modules, `virtual` and `path` are null and the module resolves
// to `<name>.zena` in the package's source directory.
// `path` overrides the entry file (relative to the source directory).
// For target-conditional modules, `virtual` maps target names to entry file
// paths (relative to the source directory).
export final class ModuleExport {
  virtual: HashMap<String, String> | null;
  path: String | null;
  // Part of the package's own machinery rather than its API. It keeps a
  // manifest entry, because that is what selects a file per target and
  // what makes the name resolve at all, but only modules of the same
  // package may import it, and documentation tools leave it out.
  internal: boolean;

  new(virtual: HashMap<String, String> | null, path: String | null = null,
      internal: boolean = false)
    : virtual = virtual, path = path, internal = internal;
}

// Configuration for a package in the package manifest.
//
// A package maps a name (e.g., "zena", "compiler") to a root directory
// containing .zena source files. Packages can optionally restrict which
// modules are importable via `exports`; files not listed there are private
// to the package and reachable only via relative imports.
export final class PackageConfig {
  // Absolute path to the package root directory.
  root: String;

  // Explicit module exports. If null, all .zena files are importable (open
  // package). If present, only listed modules can be imported (closed package).
  // A published package's are read from its manifest once it is in the
  // cache, after the config is made.
  var exports: HashMap<String, ModuleExport> | null;

  // WIT-backed package: the path to a .wit file, or a directory of them,
  // declared with `{"wit": "./path"}` in the manifest. Its modules are
  // WIT interfaces — `import {now} from 'wasi:clocks/monotonic-clock'` —
  // and the compiler host synthesizes their Zena declarations from the
  // WIT source (docs/design/component-model.md, Part 2). On `zena`, this
  // points to `host-wit` so `zena:host/*` interfaces resolve alongside
  // the standard library's `.zena` modules.
  var witRoot: String | null = null;

  // A package the resolution file pins (its `resolved` section), keyed by
  // DID and major version, `did:plc:...@1`: the local names its own
  // imports use, each mapped to the key of the package it stands for.
  // Such a package sees only these names, the standard library and
  // WIT-backed packages. Null for a package listed by path, whose files
  // see the project's names.
  var dependencies: HashMap<String, String> | null = null;

  // One of the project's dependency names (the resolution file's
  // `dependencies` section): the key of the resolved package the name
  // stands for. An alias has no root of its own.
  var aliasOf: String | null = null;

  // The directory, relative to `root`, that library names and export
  // entry files are measured from: a manifest's `source`, `src` when it
  // has none (package-manifest.md, "source"). `.` for the libraries at
  // the root, as the standard library's are.
  var source = ".";

  // The library an import of the package's name alone imports: the
  // manifest's `main`, `main` when it has none (import-names.md, "The
  // main library").
  var main = "main";

  new(
    root: String,
    exports: HashMap<String, ModuleExport> | null
  ) : root = root, exports = exports;

  // The directory libraries are in: `root` joined with `source`.
  libraryRoot: String {
    get {
      return if (this.source == ".") this.root else `${this.root}/${this.source}`;
    }
  }
}

// ============================================================================
// Resolution Result
// ============================================================================

// A resolved module with its canonical path and package info.
export final class ResolvedModule(
  // Canonical path. For stdlib, either a name id ("zena:regex") for a
  // manifest module resolving to its default "<name>.zena" file, or a path
  // id ("zena:console/host.zena") for any other stdlib file.
  // For file modules: "/absolute/path/to/module.zena".
  path: String,

  // The package this module belongs to. Empty string for relative imports
  // that don't fall under any known package.
  packageName: String
)

// ============================================================================
// Module Resolver
// ============================================================================

// Resolves import specifiers to canonical module paths.
//
// The resolver does not perform any I/O. It operates purely on its
// configuration: a map of package names to PackageConfig, and a
// compilation target string.
//
// Usage:
//   let resolver = new ModuleResolver(packages, "js");
//   let resolved = resolver.resolve("zena:regex", "/my/file.zena");
//   // resolved.path == "zena:regex"
export final class ModuleResolver {
  #packages: HashMap<String, PackageConfig>;
  #target: String;

  new(packages: HashMap<String, PackageConfig>, target: String)
    : #packages = packages, #target = target;

  // The compilation target (e.g., "core", "js", "zena-js", "component", "zena-component").
  target: String {
    get { return this.#target; }
  }

  // Resolve an import specifier relative to a referrer module.
  //
  // Specifier formats (docs/design/import-names.md):
  // - Relative: "./foo.zena", "../bar.zena"
  // - Package:  "[scope:]package[/library]", such as "acme:router/server"
  //   or "router/server"; without a library, the package's main library
  // - The standard library, the scope `zena`: "zena:regex"
  // - A WIT interface, whose namespace is a WIT dependency's name:
  //   "wasi:clocks/monotonic-clock"
  resolve(specifier: String, referrer: String): ResolvedModule {
    if (specifier.startsWith("./") || specifier.startsWith("../")) {
      return this.resolveRelative(specifier, referrer);
    }

    // A `:` before any `/` ends the scope.
    let colonPos = indexOfByte(specifier, 58); // 58 = ':'
    let slashPos = indexOfByte(specifier, 47); // 47 = '/'
    var scope: String | null = null;
    var rest = specifier;
    if (colonPos >= 0 && (slashPos < 0 || colonPos < slashPos)) {
      scope = specifier.sliceBytes(0, colonPos);
      rest = specifier.sliceBytes(colonPos + 1, specifier.length);
    }
    if (scope != null) {
      // The standard library's libraries keep their ids, `/`s and all.
      if (scope == "zena") {
        return this.resolvePackage("zena", rest, referrer);
      }
      let witKey = this.#witPackageKey(scope, referrer);
      if (witKey != null) {
        return this.resolvePackage(witKey, rest, referrer);
      }
    }
    let restSlash = indexOfByte(rest, 47);
    let packageName = if (restSlash < 0) rest else rest.sliceBytes(0, restSlash);
    let name = if (scope != null) `${scope}:${packageName}` else packageName;
    let key = this.#packageKey(name, referrer);
    let moduleName = if (restSlash < 0) this.#mainLibrary(key) else rest.sliceBytes(restSlash + 1, rest.length);
    return this.resolvePackage(key, moduleName, referrer);
  }

  // The main library of the package `key` names, through its alias if it
  // is one: the library an import of its name alone imports.
  #mainLibrary(key: String): String {
    var current = key;
    while (true) {
      if (let (true, config) = this.#packages.get(current)) {
        let aliasOf = config.aliasOf;
        if (aliasOf == null) {
          return config.main;
        }
        current = aliasOf;
      } else {
        return "main";
      }
    }
    return "main";
  }

  // The key of the WIT-backed package the scope `scope` names in an import
  // from `referrer`, or null when it names none: WIT's namespaces are the
  // scopes of its interfaces.
  #witPackageKey(scope: String, referrer: String): String | null {
    var key = scope;
    let owner = this.findPackageForPath(referrer);
    if (owner != "" && owner != "zena") {
      let dependencies = this.#packages[owner].dependencies;
      if (dependencies != null) {
        if (let (true, given) = dependencies.get(scope)) {
          key = given;
        }
      }
    }
    return if (this.#isWitPackage(key)) key else null;
  }

  // The key of the package `name` stands for in an import from
  // `referrer`. A resolved package's files resolve names through its own
  // dependencies; every other file through the package map, where the
  // project's dependency names are aliases.
  #packageKey(name: String, referrer: String): String {
    let owner = this.findPackageForPath(referrer);
    if (owner != "" && owner != "zena") {
      let dependencies = this.#packages[owner].dependencies;
      if (dependencies != null) {
        if (let (true, key) = dependencies.get(name)) {
          return key;
        }
        if (name == "zena" || this.#isWitPackage(name)) {
          return name;
        }
        throw new Error(`Package '${owner}' has no dependency named '${name}'`);
      }
    }
    return name;
  }

  #isWitPackage(name: String): boolean {
    if (let (true, config) = this.#packages.get(name)) {
      return config.witRoot != null;
    }
    return false;
  }

  // Resolve a relative import specifier.
  resolveRelative(specifier: String, referrer: String): ResolvedModule {
    // Relative imports between stdlib files resolve in the space of paths
    // relative to the stdlib source root and stay within it.
    if (referrer.startsWith("zena:")) {
      return this.#resolveStdlibRelative(specifier, referrer);
    }
    let dir = dirName(referrer);
    let resolved = normalizePath(`${dir}/${specifier}`);
    let packageName = this.findPackageForPath(resolved);
    return new ResolvedModule(resolved, packageName);
  }

  #resolveStdlibRelative(specifier: String, referrer: String): ResolvedModule {
    let refPath = this.#stdlibFilePath(referrer.sliceBytes(5, referrer.length));
    let resolved = normalizePath(`${dirName(refPath)}/${specifier}`);
    if (resolved == ".." || resolved.startsWith("../")) {
      throw new Error(
        `Cannot resolve '${specifier}' from ${referrer} (escapes the stdlib)`
      );
    }
    if (let (true, config) = this.#packages.get("zena")) {
      if (config.exports != null) {
        let exports = config.exports as HashMap<String, ModuleExport>;
        var exportEntry: ModuleExport | null = null;
        if (let (true, entry) = exports.get(resolved)) {
          exportEntry = entry;
        } else if (!resolved.endsWith(".zena")) {
          if (let (true, entry) = exports.get(resolved + ".zena")) {
            exportEntry = entry;
          }
        }
        if (exportEntry != null) {
          let virtual = (exportEntry as ModuleExport).virtual;
          if (virtual != null) {
            let virtualMap = virtual as HashMap<String, String>;
            if (let (true, entryPath) = virtualMap.get(this.#target)) {
              return makeCanonicalFilePath("zena", entryPath, config);
            }
            if (let (true, defaultPath) = virtualMap.get("default")) {
              return makeCanonicalFilePath("zena", defaultPath, config);
            }
          }
        }
      }
    }
    return new ResolvedModule("zena:" + this.#stdlibIdForPath(resolved), "zena");
  }

  // Map a stdlib canonical id (without the "zena:" prefix) to its file path
  // relative to the stdlib source root.
  #stdlibFilePath(sub: String): String {
    if (sub.endsWith(".zena")) {
      return sub;
    }
    return sub + ".zena";
  }

  // Map a stdlib-root-relative file path back to a canonical id (without the
  // "zena:" prefix): the module name when the path is the default entry file
  // of a manifest module, otherwise the path itself. Modules with an explicit
  // `path` or a `virtual` mapping always canonicalize to path ids, so each
  // file has exactly one canonical id.
  #stdlibIdForPath(path: String): String {
    if (path.contains("/") || !path.endsWith(".zena")) {
      return path;
    }
    let name = path.sliceBytes(0, path.length - 5);
    if (let (true, config) = this.#packages.get("zena")) {
      if (config.exports != null) {
        let exports = config.exports as HashMap<String, ModuleExport>;
        if (let (true, moduleExport) = exports.get(name)) {
          if (moduleExport.virtual == null && moduleExport.path == null) {
            return name;
          }
        }
      }
    }
    return path;
  }

  // Resolve a package import specifier.
  resolvePackage(
    packageName: String,
    moduleName: String,
    referrer: String
  ): ResolvedModule {
    if (let (true, config) = this.#packages.get(packageName)) {
      let aliasOf = config.aliasOf;
      if (aliasOf != null) {
        return this.resolvePackage(aliasOf, moduleName, referrer);
      }

      // A WIT-backed package: the module is a WIT interface, and the
      // canonical path carries everything the host needs to synthesize
      // its declarations — where the WIT lives, and which interface.
      // The specifier has no version on purpose; the WIT declares it.
      let witRoot = config.witRoot;
      if (config.exports == null && witRoot != null) {
        return new ResolvedModule(
            `wit:${witRoot as String}#${packageName}:${moduleName}`,
            packageName);
      }

      // Check exports if the package has an explicit export list.
      if (config.exports != null) {
        let exports = config.exports as HashMap<String, ModuleExport>;
        if (!exports.has(moduleName)) {
          if (witRoot != null && moduleName.startsWith("host/")) {
            return new ResolvedModule(
                `wit:${witRoot}#${packageName}:${moduleName}`,
                packageName);
          }
          throw new Error(
            `Library '${moduleName}' not found in package '${packageName}'`
          );
        }

        let moduleExport = exports[moduleName];

        // An internal module is the package's own machinery. It is in the
        // export map because that is what selects its file per target and
        // what makes the name resolve, and not because anyone outside may
        // name it.
        if (moduleExport.internal &&
            this.findPackageForPath(referrer) != packageName) {
          throw new Error(
            "Library '" + packageName + ":" + moduleName + "' is internal to '" +
              packageName + "' and cannot be imported from outside it"
          );
        }

        // Resolve virtual modules (target-conditional) to their entry file.
        // A module with no entry for the current target is not available
        // there, and says so: falling through would resolve to a default
        // entry file that does not exist, and report a missing file
        // instead of a missing capability.
        if (moduleExport.virtual != null) {
          let virtual = moduleExport.virtual as HashMap<String, String>;
          if (let (true, entryPath) = virtual.get(this.#target)) {
            return makeCanonicalFilePath(packageName, entryPath, config);
          }
          if (let (true, defaultPath) = virtual.get("default")) {
            return makeCanonicalFilePath(packageName, defaultPath, config);
          }
          throw new Error(
            "Library '" + packageName + ":" + moduleName +
              "' is not available on target '" + this.#target + "'"
          );
        }

        // Modules with an explicit entry file resolve to it.
        if (moduleExport.path != null) {
          return makeCanonicalFilePath(
            packageName,
            moduleExport.path as String,
            config
          );
        }
      }

      return makeCanonicalPath(packageName, moduleName, config);
    }

    throw new Error(`Unknown package: '${packageName}'`);
  }

  // Find which package (if any) contains the given path: the one with the
  // longest root the path is inside, so a package nested in another's
  // directory owns its own files. WIT-backed packages and aliases have no
  // root and own nothing.
  findPackageForPath(path: String): String {
    if (path.startsWith("zena:")) {
      return "zena";
    }
    var found = "";
    var foundLength = -1;
    let iter = this.#packages.keys();
    for (let name in iter) {
      let root = this.#packages[name].root;
      if (root == "" || !isUnder(path, root)) {
        continue;
      }
      // A HashMap's order varies between processes, so equal roots are
      // decided by name.
      if (root.length > foundLength || (root.length == foundLength && name.compareTo(found) < 0)) {
        found = name;
        foundLength = root.length;
      }
    }
    return found;
  }
}

// ============================================================================
// Path Utilities
// ============================================================================

// Whether `path` is `root` or a file under it. A root of `.`, the workspace's
// own directory, holds every relative path that does not climb out of it.
function isUnder(path: String, root: String): boolean {
  if (root == ".") {
    return !path.startsWith("/") && !path.startsWith("../") && path != ".." &&
        !path.startsWith("zena:") && !path.startsWith("wit:");
  }
  return path == root || path.startsWith(`${root}/`);
}

// Map a stdlib canonical id (with or without the "zena:" prefix) to its file
// path relative to the stdlib source root. Name ids ("zena:string") map to
// "<name>.zena"; path ids ("zena:console/host.zena") contain the file path.
export function stdlibIdToRelativeFile(id: String): String {
  let sub = if (id.startsWith("zena:")) id.sliceBytes(5, id.length) else id;
  if (sub.endsWith(".zena")) {
    return sub;
  }
  return sub + ".zena";
}

// Create a canonical path for a module resolving to its default
// "<name>.zena" entry file.
// Stdlib modules use the "zena:" prefix; other packages resolve to file paths.
function makeCanonicalPath(
  packageName: String,
  moduleName: String,
  config: PackageConfig
): ResolvedModule {
  if (packageName == "zena") {
    return new ResolvedModule("zena:" + moduleName, "zena");
  }
  let filePath = `${config.libraryRoot}/${moduleName}.zena`;
  return new ResolvedModule(filePath, packageName);
}

// Create a canonical path for a module with an explicit entry file
// (from `path` or a `virtual` mapping), given relative to the package's
// source directory.
// Stdlib entries become path ids ("zena:console/host.zena").
function makeCanonicalFilePath(
  packageName: String,
  entryPath: String,
  config: PackageConfig
): ResolvedModule {
  if (packageName == "zena") {
    return new ResolvedModule("zena:" + entryPath, "zena");
  }
  return new ResolvedModule(`${config.libraryRoot}/${entryPath}`, packageName);
}

// Find the byte position of the first occurrence of a byte in a string.
// Returns -1 if not found.
export function indexOfByte(s: String, byte: i32): i32 {
  var i = 0;
  while (i < s.length) {
    if (s.getByteAt(i) == byte) {
      return i;
    }
    i += 1;
  }
  return 0 - 1;
}

// Get the directory portion of a path.
// e.g., "/foo/bar/baz.zena" → "/foo/bar"
// Returns "." if the path has no directory separator.
// Note: "zena:" canonical ids must not be passed here — the resolver maps
// them to stdlib-root-relative file paths first (see #resolveStdlibRelative).
export function dirName(path: String): String {
  var lastSlash = 0 - 1;
  var i = 0;
  while (i < path.length) {
    if (path.getByteAt(i) == 47) { // 47 = '/'
      lastSlash = i;
    }
    i += 1;
  }
  if (lastSlash < 0) {
    return ".";
  }
  return path.sliceBytes(0, lastSlash);
}

// Normalize a path by resolving "." and ".." segments.
// Preserves leading "/" for absolute paths.
export function normalizePath(path: String): String {
  let segments = splitByByte(path, 47); // 47 = '/'
  let result = new Array<String>();
  let isAbsolute = path.length > 0 && path.getByteAt(0) == 47;

  for (let seg in segments) {
    if (seg == "." || seg == "") {
      // Skip "." and empty segments (from "//")
    } else if (seg == "..") {
      if (result.length > 0 && result[result.length - 1] != "..") {
        result.pop();
      } else if (!isAbsolute) {
        // Preserve leading ".." segments in relative paths so callers can
        // detect escapes above the base directory. (Above the root of an
        // absolute path, ".." is dropped as before.)
        result.push(seg);
      }
    } else {
      result.push(seg);
    }
  }

  if (isAbsolute) {
    return "/" + joinBySlash(result);
  }
  if (result.length == 0) {
    return ".";
  }
  return joinBySlash(result);
}

// Split a string by a byte delimiter.
export function splitByByte(s: String, delim: i32): GrowableArray<String> {
  let parts = new Array<String>();
  var start = 0;
  var i = 0;
  while (i < s.length) {
    if (s.getByteAt(i) == delim) {
      parts.push(s.sliceBytes(start, i));
      start = i + 1;
    }
    i += 1;
  }
  parts.push(s.sliceBytes(start, s.length));
  return parts;
}

// Join an array of path segments with "/".
function joinBySlash(segments: GrowableArray<String>): String {
  if (segments.length == 0) {
    return "";
  }
  var result = segments[0];
  var i = 1;
  while (i < segments.length) {
    result = `${result}/${segments[i]}`;
    i += 1;
  }
  return result;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19