compiler 0.0.2-preview.1
The Zena self-hosted compiler
compiler#
The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).
Usage#
Parsing a Single File#
Use compiler/parser to parse Zena source text into an AST (Module):
import { parse } from 'compiler/parser';
let ast = parse('export let answer = 42;', 'example.zena');
Loading and Checking a Program#
Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:
import {
createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';
let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
stdlibRoot,
packages,
});
let result = await compiler.compile({
entry: '/workspace/main.zena',
target: 'host',
});
let checked = checkCompilation(result);
Compiling a File to WebAssembly#
Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:
import { compileFile } from 'compiler/compile-file';
let ok = await compileFile({
entry: 'src/main.zena',
outPath: 'out/main.wasm',
stdlibRoot: '/stdlib',
});
Libraries#
compiler/compiler/compiler— compiler entry point (Compiler,createCompiler,checkCompilation,ProgramCheckResult)compiler/compile-file— end-to-end file compilation (compileFile,CompileFileOptions)compiler/tokenizer— lexer and token definitions (tokenize,Token,TokenType)compiler/parser— recursive-descent parser (parse,Parser)compiler/ast— AST node definitions (Node,Module,Statement,Expression,TypeAnnotation)compiler/visitor— AST traversal helpers (walk,Visitor)compiler/scope— lexical scope and symbol resolution (ScopeBuilder,ScopeResult,Symbol)compiler/checker— static type checker (checkModule,CheckResult)compiler/semantic-model— semantic queries over a checked module (SemanticModel)compiler/types— compiler type representations (Type,ClassType,FunctionType,typeToString)compiler/diagnostics— compiler diagnostics and source spans (Diagnostic,DiagnosticCode,DiagnosticSeverity,SourceSpan)compiler/package-manifest—zena-package.jsonmanifest and workspace loader (loadWorkspace,loadPackageMap)compiler/module-resolver— package and relative module specifier resolution (ModuleResolver,PackageConfig)compiler/library-loader— module graph loader (LibraryLoader,CompilerHost,SourceFile)compiler/codegen/binary-generator— WebAssembly GC binary emitter (BinaryGenerator)compiler/codegen/wat-generator— WebAssembly Text (WAT) emitter (WatGenerator)
License#
MIT
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;
}
- zena-lang:wit-parser wit-parser.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|