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

18.0 KiB Raw
import { BlockStatement, Expression, ExpressionStatement, Node } from '../ast.zena';
import {
  ArrayType as ArrayT, BooleanType, ClassType, ErrorType, FunctionType, InterfaceType, RecordType as RecordT, TupleType as TupleT, Type, TypeParameterType, UnionType as UnionT, baseType, instantiateClassType, isNullableType, isNumericType, typeContainsTypeParameter, typeToString, unwrapAliases
} from '../types.zena';
import { FunctionAdaptationDependency, TupleWidening } from '../semantic-model.zena';
import { DiagnosticCode } from '../diagnostics.zena';
import { WellKnown } from '../well-known.zena';
import { CheckerContext } from './context.zena';
import { tryInstantiateGenericFunction } from './generics.zena';
import { recordUnionMembersOf } from './members.zena';
import { isAssignableTo, isWellKnownClassType, typesEqual } from './relations.zena';
import { subtractNullFromType } from './unions.zena';
import { growable } from 'zena:core';

/**
 * Notes the record types `source` brings into a slot of type `target`
 * when that slot does not know their shape: anything but a single record
 * type, so `anyref`, `eqref`, or a union with other kinds of value. A
 * record in such a slot can reach the erased `==`, which compares it by
 * shape only if it was noted here (#399). An existential record type is
 * such a slot too: its `==` compares the records it holds the same way.
 * A type parameter is not: its code is specialized per argument.
 */
function noteRecordErasure(ctx: CheckerContext, source: Type, target: Type) {
  // An inline record slot is its record's fields: it knows the shape.
  let targetBase = baseType(unwrapAliases(subtractNullFromType(target)));
  if (targetBase is RecordT) {
    let targetRecord = targetBase;
    if (!targetRecord.isExistential) {
      return;
    }
  } else if (targetBase is TypeParameterType || targetBase is ErrorType) {
    return;
  }
  match (baseType(unwrapAliases(subtractNullFromType(source)))) {
    case RecordT as rec: {
      noteErasedRecord(ctx, rec);
    }
    case UnionT {types}: {
      for (let member in types) {
        let memberBase = baseType(unwrapAliases(member));
        if (memberBase is RecordT) {
          noteErasedRecord(ctx, memberBase);
        }
      }
    }
    case _: {}
  }
}

/**
 * Notes the tuples `source` brings into a slot of type `target`: each
 * pair of tuple types where a tuple of one is used as a tuple of the
 * other, outermost and nested (`tupleWidenings`), and each tuple type put
 * into a slot that does not know it (`erasedTupleTypes`). Codegen joins
 * the representations of the types that meet (#1137). A type parameter
 * knows its tuple: its code is specialized per argument.
 */
export function noteTupleWidening(ctx: CheckerContext, source: Type, target: Type): void {
  let s = baseType(unwrapAliases(subtractNullFromType(source)));
  let t = baseType(unwrapAliases(subtractNullFromType(target)));
  if (t is TypeParameterType || t is ErrorType || s is ErrorType) {
    return;
  }
  if (s is UnionT) {
    for (let member in s.types) {
      noteTupleWidening(ctx, member, target);
    }
    return;
  }
  // An immutable array widens in its element: the tuples in it are used
  // as tuples of the target's element type.
  if (s is ClassType && t is ClassType &&
      isWellKnownClassType(ctx, s, WellKnown.ImmutableArrayClass) &&
      isWellKnownClassType(ctx, t, WellKnown.ImmutableArrayClass)) {
    let sArgs = s.typeArguments;
    let tArgs = t.typeArguments;
    if (sArgs != null && tArgs != null && sArgs.length == 1 && tArgs.length == 1) {
      noteTupleWidening(ctx, sArgs[0], tArgs[0]);
    }
    return;
  }
  if (s is ArrayT && t is ArrayT) {
    if (!s.elementsMutable && !t.elementsMutable) {
      noteTupleWidening(ctx, s.elementType, t.elementType);
    }
    return;
  }
  if (s is FunctionType && t is FunctionType) {
    // A result passes out, a parameter in.
    noteTupleWidening(ctx, s.returnType, t.returnType);
    let n = if (s.parameters.length < t.parameters.length) s.parameters.length
        else t.parameters.length;
    for (var i = 0; i < n; i += 1) {
      noteTupleWidening(ctx, t.parameters[i], s.parameters[i]);
    }
    return;
  }
  if (!(s is TupleT)) {
    return;
  }
  if (t is TupleT) {
    noteTuplePair(ctx, s, t);
    return;
  }
  if (t is UnionT) {
    for (let member in t.types) {
      let m = baseType(unwrapAliases(member));
      if (m is TupleT && isAssignableTo(ctx, s, m)) {
        noteTuplePair(ctx, s, m);
        return;
      }
    }
  }
  noteErasedTuple(ctx, s);
}

/** Notes a tuple of type `s` used as one of type `t`, and their elements. */
function noteTuplePair(ctx: CheckerContext, s: TupleT, t: TupleT): void {
  if (s.elementTypes.length != t.elementTypes.length || typesEqual(s, t)) {
    return;
  }
  ctx.model.tupleWidenings.push(new TupleWidening(s, t));
  for (var i = 0; i < s.elementTypes.length; i += 1) {
    noteTupleWidening(ctx, s.elementTypes[i], t.elementTypes[i]);
  }
}

/** Notes `t`, a tuple type, put into a slot that does not know it. */
function noteErasedTuple(ctx: CheckerContext, t: TupleT): void {
  for (let noted in ctx.model.erasedTupleTypes) {
    if (noted === t) {
      return;
    }
  }
  ctx.model.erasedTupleTypes.push(t);
}

/**
 * Notes the tuple types `target` names when a value of type `source` is
 * tested or cast to it (`is`, `as`) and `source` is not a tuple type
 * itself: the value may be a tuple of another type of the same family,
 * erased (`testedTupleTypes`, #1181).
 */
export function noteTupleTest(ctx: CheckerContext, source: Type, target: Type): void {
  if (baseType(unwrapAliases(subtractNullFromType(source))) is TupleT) {
    return;
  }
  let t = baseType(unwrapAliases(subtractNullFromType(target)));
  let members = if (t is UnionT) t.types else growable<Type>([t]);
  for (let member in members) {
    let m = baseType(unwrapAliases(member));
    if (m is TupleT) {
      var seen = false;
      for (let noted in ctx.model.testedTupleTypes) {
        if (noted === m) {
          seen = true;
        }
      }
      if (!seen) {
        ctx.model.testedTupleTypes.push(m);
      }
    }
  }
}

/**
 * When `existential` is an existential record type and `other` a closed
 * one, notes `other` for the erased `==` they compare through.
 */
export function noteExistentialComparison(ctx: CheckerContext, existential: Type, other: Type): void {
  let e = baseType(unwrapAliases(subtractNullFromType(existential)));
  let o = baseType(unwrapAliases(subtractNullFromType(other)));
  if (e is RecordT && o is RecordT) {
    let eRecord = e;
    let oRecord = o;
    if (eRecord.isExistential && !oRecord.isExistential) {
      noteErasedRecord(ctx, oRecord);
    }
  }
}

/** Notes `rec`, and the record types in its fields, which compare through the same erased `==`. */
function noteErasedRecord(ctx: CheckerContext, rec: RecordT): void {
  // An existential is no shape; the records packed into it were noted
  // where they were packed.
  if (rec.row != null || rec.isExistential) {
    return;
  }
  for (let noted in ctx.model.erasedRecordTypes) {
    if (noted === rec) {
      return;
    }
  }
  ctx.model.erasedRecordTypes.push(rec);
  for (let key in rec.properties.keys()) {
    let fieldBase = baseType(unwrapAliases(subtractNullFromType(rec.properties[key])));
    if (fieldBase is RecordT) {
      noteErasedRecord(ctx, fieldBase);
    }
  }
}

/**
 * The `Box<P>` a tag's value type accepts for a primitive interpolation
 * of type `primitive`, or null when it accepts none. Accepting the box
 * is how a tag opts into boxing (docs/design/wasm-web-ui.md, "Zena
 * changes"); the box's constructor is referenced so reachability keeps
 * it, since no expression names the class.
 */
export function boxForTemplateValue(ctx: CheckerContext, primitive: Type, valueType: Type): ClassType | null {
  let base = baseType(primitive);
  if (!(isNumericType(base) || base is BooleanType) || typeContainsTypeParameter(base)) {
    return null;
  }
  let boxGeneric = ctx.tryResolveWellKnownType(WellKnown.BoxClass);
  if (boxGeneric == null || !(boxGeneric is ClassType)) {
    return null;
  }
  let generic = boxGeneric;
  let args = growable<Type>([base]);
  let boxed = instantiateClassType(generic, args);
  if (!isAssignableTo(ctx, boxed, valueType)) {
    return null;
  }
  let deps = ctx.currentDependencies();
  if (deps != null) {
    deps.referencedTypes.add(boxed as Type);
  }
  ctx.referenceClassMethod(generic, "<constructor>");
  return boxed;
}

export function checkAndRegisterInterfaceAdaptation(ctx: CheckerContext, node: Node, sourceType: Type, targetType: Type): void {
  noteRecordErasure(ctx, sourceType, targetType);
  noteTupleWidening(ctx, sourceType, targetType);
  // `C | null` is assignable to no single member of `I | null`, so the
  // payloads are what the adaptation is about: peel null off the source
  // and match that against the target's members. The peeled fact is
  // carried to codegen, which packs the fat pointer under a null guard
  // (null stays null rather than becoming a pointer to nothing).
  let sourceIsNullable = isNullableType(sourceType);
  let effectiveSource = unwrapAliases(if (sourceIsNullable) subtractNullFromType(sourceType)
      else sourceType);

  var effectiveTarget = unwrapAliases(targetType);
  if (let UnionT {types} = effectiveTarget) {
    for (let member in types) {
      if (isAssignableTo(ctx, effectiveSource, member)) {
        effectiveTarget = unwrapAliases(member);
        break;
      }
    }
  }

  // A class that does not implement the interface has no pack: a
  // downcast of one (`animal as Named`) is answered by the class's type
  // info at run time (docs/design/interface-type-tests.md).
  if (effectiveSource is ClassType && effectiveTarget is InterfaceType &&
      isAssignableTo(ctx, effectiveSource, effectiveTarget)) {
    if (ctx.warnUnnecessaryCasts && ctx.model.getInterfaceAdaptationDirect(node) == null) {
      ctx.warning("'" + typeToString(effectiveSource) + "' is boxed to pass as '" +
          typeToString(effectiveTarget) + "': an allocation here and an indirect call at each use.",
          DiagnosticCode.Adaptation, node.loc);
    }
    ctx.model.setInterfaceAdaptation(node, effectiveSource, effectiveTarget,
        sourceIsNullable);
    let deps = ctx.currentDependencies();
    if (deps != null) {
      let classSymId = (effectiveSource.genericSource ?? effectiveSource).symbolId;
      let ifaceSymId = (effectiveTarget.genericSource ?? effectiveTarget).symbolId;
      let key = `${i32ToString(classSymId as i32)}::${i32ToString(ifaceSymId as i32)}`;
      deps.usedInterfaceAdaptations.add(key);
    }
  } else if (effectiveSource is InterfaceType && effectiveTarget is InterfaceType &&
      !typesEqual(effectiveSource, effectiveTarget) &&
      isAssignableTo(ctx, effectiveSource, effectiveTarget)) {
    ctx.model.setInterfaceAdaptation(node, effectiveSource, effectiveTarget,
        sourceIsNullable);
    // The upcast copies the target's vtable slots out of the source's.
    // It references no member itself: codegen gives the target a slot
    // for each member called through it, and the source, which extends
    // the target, a slot for each of those too.
    let deps = ctx.currentDependencies();
    if (deps != null) {
      deps.referencedTypes.add(effectiveSource);
      deps.referencedTypes.add(effectiveTarget);
    }
  } else if (sourceType is FunctionType && effectiveTarget is FunctionType) {
    if (!typesEqual(sourceType, effectiveTarget)) {
      if (ctx.warnUnnecessaryCasts && ctx.model.getFunctionAdaptationDirect(node) == null) {
        ctx.warning("Function value is re-wrapped to match '" + typeToString(effectiveTarget) +
            "': an allocation here and a second call at each use.",
            DiagnosticCode.Adaptation, node.loc);
      }
      ctx.model.setFunctionAdaptation(node, sourceType, effectiveTarget);
      let deps = ctx.currentDependencies();
      if (deps != null) {
        deps.functionAdaptations.push(new FunctionAdaptationDependency(node, sourceType, effectiveTarget));
      }
    }
  }

  let nonNullSrc = unwrapAliases(subtractNullFromType(sourceType));
  let nonNullTgt = unwrapAliases(subtractNullFromType(effectiveTarget));
  if (nonNullSrc is RecordT && nonNullTgt is RecordT) {
    // A row stands for fields each specialization fills in differently,
    // so `{x: i32, ...R}` to `{x: i32}` adapts though both name only `x`.
    // So does an existential to or from a closed type naming the same
    // fields: one is a pack or projection of the other.
    var needsAdaptation = nonNullSrc.properties.size != nonNullTgt.properties.size ||
        nonNullSrc.row !== nonNullTgt.row ||
        nonNullSrc.isExistential != nonNullTgt.isExistential;
    if (!needsAdaptation) {
      let keys = nonNullSrc.properties.keys();
      for (let key in keys) {
        if (nonNullTgt.properties.has(key)) {
          let t1 = nonNullSrc.properties[key];
          let t2 = nonNullTgt.properties[key];
          if (!isAssignableTo(ctx, t1, t2) || !isAssignableTo(ctx, t2, t1)) {
            needsAdaptation = true;
          }
          // Same field set and types, but a presence difference still
          // changes the layout (the target carries a mask slot for its
          // optional fields).
          if (nonNullSrc.isOptional(key) != nonNullTgt.isOptional(key)) {
            needsAdaptation = true;
          }
        } else {
          needsAdaptation = true;
        }
      }
    }
    if (needsAdaptation) {
      if (ctx.warnUnnecessaryCasts && ctx.model.getRecordAdaptationDirect(node) == null) {
        ctx.warning("Record is copied to the shape '" + typeToString(nonNullTgt) +
            "': an allocation here.",
            DiagnosticCode.Adaptation, node.loc);
      }
      ctx.model.setRecordAdaptation(node, nonNullSrc, nonNullTgt);
    }
  }

  // A union of record types reaches the use as one of its members, and
  // each member has its own layout, so there is no single repack for
  // the union — codegen picks the member at run time and repacks that
  // one. The join that produced the union cannot do it earlier: it has
  // no one shape to adapt the arms to.
  //
  // The target here is the DECLARED one rather than the member
  // `effectiveTarget` narrowed to. A union target reads the value per
  // member itself, so repacking to one of its members drops what the
  // others hold — and the repack is a view, so the member chain at the
  // next use then casts that view's instance to the wrong layout and
  // traps.
  let declaredTgt = unwrapAliases(subtractNullFromType(targetType));
  if (nonNullSrc is UnionT && declaredTgt is RecordT) {
    let members = recordUnionMembersOf(nonNullSrc);
    if (members != null) {
      ctx.model.setRecordUnionAdaptation(node, members, declaredTgt,
          sourceIsNullable);
    }
  }
}

/**
 * Adapts one arm of a multi-arm expression to the type its context
 * asked for, and reports the arm as having that type.
 *
 * An arm checked against a contextual type is in the same position as
 * the expression that holds it, so a class instance there has to reach
 * its consumer as a fat pointer, exactly as an initializer does. Left
 * alone, `a ?? []` in an `Array<String>` context types as
 * `Array<String> | ImmutableArray<String>` — two arms with two
 * different representations, one of which traps the moment the value
 * is read back as an interface.
 */
/**
 * The tail of checking a value against the type its position expects,
 * once assignability holds: a generic function value is instantiated
 * at the expected signature, and the node retyped with it, and a
 * crossing of a representation boundary (class to interface, function
 * re-wrapping, record repacking) is recorded for codegen. Answers the
 * type the node now has.
 */
export function adaptToExpected(ctx: CheckerContext, node: Node, actual: Type, expected: Type): Type {
  let instantiated = tryInstantiateGenericFunction(ctx, actual, expected);
  if (instantiated !== actual) {
    ctx.setNodeType(node, instantiated);
  }
  checkAndRegisterInterfaceAdaptation(ctx, node, instantiated, expected);
  return instantiated;
}

export function adaptArmToContext(
  ctx: CheckerContext,
  node: Node,
  armType: Type,
  expectedType: Type | null
): Type {
  if (expectedType == null) { return armType; }
  let target = expectedType;
  if (!(target is InterfaceType)) { return armType; }
  if (!(baseType(armType) is ClassType)) { return armType; }
  if (!isAssignableTo(ctx, armType, target)) { return armType; }
  checkAndRegisterInterfaceAdaptation(ctx, node, armType, target);
  return target;
}

/**
 * Adapts the value `??` pulls out of a maybe-form on its left.
 *
 * `m.get(k) ?? []` in an `Array<String>` context yields the tuple's
 * payload, and when that payload is a `GrowableArray<String>` it has
 * to reach the consumer as a fat pointer like any other class in an
 * interface slot. The payload is a slot of the left operand rather
 * than an expression anyone wrote, so the adaptation goes on the `??`
 * itself and the coalesce lowering applies it to that arm alone — the
 * default arm carries its own.
 */
export function adaptCoalescedArm(
  ctx: CheckerContext,
  node: Expression | null,
  armType: Type,
  expectedType: Type | null
): Type {
  if (node == null) { return armType; }
  return adaptArmToContext(ctx, node, armType, expectedType);
}

/**
 * After a join's type is known: an arm whose own type is a class the
 * join folded into an interface is adapted to that interface, as it
 * would have been had the context asked for it.
 */
export function adaptJoinedArm(ctx: CheckerContext, arm: Node, armType: Type, joined: Type): void {
  if (!(baseType(armType) is ClassType)) { return; }
  let target = subtractNullFromType(joined);
  if (!(target is InterfaceType)) { return; }
  if (typesEqual(armType, target)) { return; }
  if (!isAssignableTo(ctx, armType, target)) { return; }
  checkAndRegisterInterfaceAdaptation(ctx, arm, armType, target);
}

/** The expression a branch's value comes from: a block's last expression statement, else the node. */
export function armValueNode(node: Node): Node | null {
  if (node is BlockStatement) {
    if (node.body.length == 0) { return null; }
    let last = node.body[node.body.length - 1];
    return if (last is ExpressionStatement) last.expression else null;
  }
  return node;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19