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

16.9 KiB Raw
import { growable } from 'zena:core';
import { Expression, FunctionExpression, SourceLocation } from '../ast.zena';
import {
  ClassType, FunctionType, InterfaceType, NeverType, Type, TypeParameterType,
  UnionType as UnionT, VoidType, instantiateFunctionType, isScopedType,
  scopedInner, unwrapAliases
} from '../types.zena';
import { DiagnosticCode } from '../diagnostics.zena';
import { CheckerContext } from './context.zena';
import { substituteTypeParams } from './generics.zena';
import { argumentAdaptsToParameter } from './literals.zena';
import { extractFutureValueType } from './protocols.zena';
import { isAssignableTo, typesEqual } from './relations.zena';

/**
 * Fills `applicableRaw`/`applicableRes` with the operator candidates
 * the given operands are applicable to — the `[]` read sites, whose
 * one operand is the index, and the `[]=` write site, whose two are
 * the index and the value.
 *
 * Same two tiers as a call (member-lookup.md §5.1): operands are
 * first judged by the types they already have, and only if that
 * leaves nothing applicable does a bare numeric literal operand adapt
 * to the parameter facing it. Without the second tier `t[10]` cannot
 * reach an `operator [](k: u32)` at all.
 *
 * Only the first `adaptableCount` operands may adapt. `[]=` passes 1,
 * so its index adapts and its value does not: under a compound
 * assignment the value operand is the right side of the `+=`, not the
 * value being stored, and its type is already `effectiveType`.
 *
 * The two output arrays are parallel because callers need both forms:
 * the declared signature to record the selection for codegen, and the
 * substituted one to compare specificity.
 */
/** `ft` and each of its overloads: the candidates a selection runs over. */
export function overloadCandidates(ft: FunctionType): GrowableArray<FunctionType> {
  let candidates = growable<FunctionType>([ft]);
  let {overloads} = ft;
  if (overloads != null) {
    for (let overload in overloads) {
      candidates.push(overload);
    }
  }
  return candidates;
}

export function collectApplicableOperatorOverloads(
  ctx: CheckerContext,
  candidates: GrowableArray<FunctionType>,
  typeParams: Array<TypeParameterType> | null,
  typeArgs: Array<Type> | null,
  operandTypes: Array<Type>,
  operands: GrowableArray<Expression>,
  adaptableCount: i32,
  applicableRaw: GrowableArray<FunctionType>,
  applicableRes: GrowableArray<FunctionType>
): void {
  for (var tier = 0; tier < 2; tier += 1) {
    let adaptLiterals = tier == 1;
    for (let candidate in candidates) {
      let resolvedCandidate =
          substituteTypeParams(typeParams, typeArgs, candidate) as FunctionType;
      if (resolvedCandidate.parameters.length != operandTypes.length) {
        continue;
      }
      var matchOk = true;
      for (var i = 0; i < operandTypes.length; i += 1) {
        let param = resolvedCandidate.parameters[i];
        if (!isAssignableTo(ctx, operandTypes[i], param) &&
            !(i < adaptableCount &&
              asyncNeverClosureAdaptsTo(ctx, operands[i], operandTypes[i], param)) &&
            !(adaptLiterals && i < adaptableCount &&
              argumentAdaptsToParameter(operands[i], param))) {
          matchOk = false;
        }
      }
      if (matchOk) {
        applicableRaw.push(candidate);
        applicableRes.push(resolvedCandidate);
      }
    }
    if (applicableRaw.length > 0) {
      return;
    }
  }
}

// ============================================================================
// Class & Interface Checking
// ============================================================================
/**
 * `a` with its own type parameters replaced by `b`'s, position by
 * position, when both are generic over the same number of parameters;
 * `a` itself otherwise. Two generic methods have the same signature
 * when they agree up to the names of their parameters — `measure<T>(tag:
 * T)` overrides `measure<U>(tag: U)` — and a parameter is the same only
 * as the same object, so one side is renamed into the other before
 * the comparison.
 */
export function alignTypeParameters(a: FunctionType, b: FunctionType): FunctionType {
  let aParams = a.typeParameters;
  let bParams = b.typeParameters;
  if (aParams == null || bParams == null || aParams.length == 0 ||
      aParams.length != bParams.length) {
    return a;
  }
  let args = new Array<Type>();
  for (let tp in bParams) {
    args.push(tp as Type);
  }
  return instantiateFunctionType(a, args);
}

export function hasSameSignature(a: FunctionType, b: FunctionType): boolean {
  if (a.parameters.length != b.parameters.length) {
    return false;
  }
  let aligned = alignTypeParameters(a, b);
  for (var i = 0; i < aligned.parameters.length; i += 1) {
    if (!typesEqual(aligned.parameters[i], b.parameters[i])) {
      return false;
    }
  }
  return true;
}

/**
 * The signatures a member type stands for: each overload of an overloaded
 * method, or the type itself.
 */
export function functionSignatures(t: Type): Array<Type> {
  let signatures = new Array<Type>();
  if (t is FunctionType) {
    let {overloads} = t;
    if (overloads != null) {
      for (let overload in overloads) {
        signatures.push(overload);
      }
      return signatures;
    }
  }
  signatures.push(t);
  return signatures;
}

export function findMatchingOverload(
  method: FunctionType,
  signature: FunctionType
): FunctionType | null {
  if (hasSameSignature(method, signature)) {
    return method;
  }
  if (method.overloads != null) {
    let overloads = method.overloads as GrowableArray<FunctionType>;
    for (let overload in overloads) {
      if (hasSameSignature(overload, signature)) {
        return overload;
      }
    }
  }
  return null;
}

/**
 * Whether `arg` is an unannotated `async` function literal whose body never
 * returns a value (`Future<never>`), facing a parameter expecting `Future<V>`.
 * `Future<T>` is nominal and invariant, so the pre-pass leaves the closure's
 * return type as `Future<never>` (avoiding premature adoption of whichever
 * overload was declared first) and checks parameter compatibility here;
 * re-checking against the winning overload then adopts `Future<V>`.
 */
function asyncNeverClosureAdaptsTo(
  ctx: CheckerContext,
  arg: Expression,
  argType: Type,
  param: Type
): boolean {
  if (arg is FunctionExpression) {
    if (!arg.isAsync || arg.isGenerator || arg.returnType != null) {
      return false;
    }
    let uArg = unwrapAliases(argType);
    if (uArg is FunctionType) {
      let actualVal = extractFutureValueType(ctx, unwrapAliases(uArg.returnType));
      if (actualVal == null || !(actualVal is NeverType)) {
        return false;
      }
      let uParam = unwrapAliases(param);
      if (uParam is FunctionType) {
        var paramRet = unwrapAliases(uParam.returnType);
        if (isScopedType(paramRet)) {
          paramRet = scopedInner(paramRet) ?? paramRet;
        }
        if (extractFutureValueType(ctx, paramRet) == null) {
          return false;
        }
        let adapted = new FunctionType(
            uArg.parameters, uParam.returnType, uArg.info, uArg.typeParameters);
        return isAssignableTo(ctx, adapted, param);
      }
    }
  }
  return false;
}

/**
 * Parameter-wise specificity for `atLeastAsSpecific`. Beyond direct
 * assignability, a synchronous `never`-returning function argument is
 * assignable to both `(P) => void` and `(P) => R` (non-void), which are
 * otherwise disjoint in Zena (`() => R` is not assignable to `() => void`).
 * Prefer `(P) => void` over `(P) => R` when `xParam`'s parameters and
 * modifiers are at least as specific as `yParam`'s; two non-void returns
 * (`() => i32` vs `() => String`) stay incomparable and report ambiguity.
 */
function parameterAtLeastAsSpecific(
  ctx: CheckerContext,
  xParam: Type,
  yParam: Type,
  argType: Type | null
): boolean {
  if (isAssignableTo(ctx, xParam, yParam)) {
    return true;
  }
  if (argType == null) {
    return false;
  }
  let uArg = unwrapAliases(argType);
  if (uArg is FunctionType) {
    let uArgRet = unwrapAliases(uArg.returnType);
    if (uArgRet is NeverType) {
      let uX = unwrapAliases(xParam);
      let uY = unwrapAliases(yParam);
      if (uX is FunctionType && uY is FunctionType &&
          unwrapAliases(uX.returnType) is VoidType &&
          !(unwrapAliases(uY.returnType) is VoidType)) {
        let adaptedX = new FunctionType(
            uX.parameters, new NeverType(), uX.info, uX.typeParameters);
        return isAssignableTo(ctx, adaptedX, yParam);
      }
    }
    let argFutVal = extractFutureValueType(ctx, uArgRet);
    if (argFutVal != null && argFutVal is NeverType) {
      let uX = unwrapAliases(xParam);
      let uY = unwrapAliases(yParam);
      if (uX is FunctionType && uY is FunctionType) {
        let xFutVal = extractFutureValueType(ctx, unwrapAliases(uX.returnType));
        let yFutVal = extractFutureValueType(ctx, unwrapAliases(uY.returnType));
        if (xFutVal != null && xFutVal is NeverType &&
            yFutVal != null && !(yFutVal is NeverType)) {
          let adaptedX = new FunctionType(
              uX.parameters, uY.returnType, uX.info, uX.typeParameters);
          return isAssignableTo(ctx, adaptedX, yParam);
        }
      }
    }
  }
  return false;
}

/**
 * Overload selection (member-lookup.md §5.1): X is at least as
 * specific as Y, over the call's first argCount parameters, when
 * every parameter of X is assignable to Y's corresponding parameter.
 */
function atLeastAsSpecific(
  ctx: CheckerContext,
  x: FunctionType,
  y: FunctionType,
  argCount: i32,
  argTypes: Array<Type> | null = null
): boolean {
  var i = 0;
  while (i < argCount && i < x.parameters.length && i < y.parameters.length) {
    let argType = if (argTypes != null && i < argTypes.length) argTypes[i] else null;
    if (!parameterAtLeastAsSpecific(ctx, x.parameters[i], y.parameters[i], argType)) {
      return false;
    }
    i += 1;
  }
  return true;
}

/**
 * Picks the most-specific applicable overload (member-lookup.md
 * §5.1): the unique applicable candidate at least as specific as
 * every other. Parameter-equivalent ties break toward the
 * exact-arity candidate; a set with no unique maximum is AMBIGUOUS —
 * returns (first-declared, true) so the caller can report the error
 * and still recover deterministically.
 */
function pickMostSpecificOverload(
  ctx: CheckerContext,
  applicable: GrowableArray<FunctionType>,
  argCount: i32,
  argTypes: Array<Type> | null = null
): (FunctionType, boolean) {
  var best = applicable[0];
  for (var i = 1; i < applicable.length; i += 1) {
    let c = applicable[i];
    let cBeatsBest = atLeastAsSpecific(ctx, c, best, argCount, argTypes);
    let bestBeatsC = atLeastAsSpecific(ctx, best, c, argCount, argTypes);
    if (cBeatsBest && !bestBeatsC) {
      best = c;
    } else if (cBeatsBest && bestBeatsC &&
        c.parameters.length == argCount &&
        best.parameters.length != argCount) {
      best = c;
    }
  }
  for (var i = 0; i < applicable.length; i += 1) {
    if (!atLeastAsSpecific(ctx, best, applicable[i], argCount, argTypes)) {
      return (applicable[0], true);
    }
  }
  return (best, false);
}

/**
 * Shared tail of overload selection (member-lookup.md §5.1): the
 * most-specific candidate among the applicable ones, compared over
 * the (substituted) resolved forms, reporting the ambiguity error at
 * `loc`. Returns an index into the array so callers holding parallel
 * raw/resolved arrays can recover the declared signature; -1 when
 * nothing is applicable. Every overloaded selection site — calls,
 * index reads, index writes — funnels through this.
 */
export function selectMostSpecificIndex(
  ctx: CheckerContext,
  applicableRes: GrowableArray<FunctionType>,
  argCount: i32,
  loc: SourceLocation | null,
  argTypes: Array<Type> | null = null
): i32 {
  if (applicableRes.length == 0) {
    return -1;
  }
  if (applicableRes.length == 1) {
    return 0;
  }
  let (winner, ambiguous) = pickMostSpecificOverload(ctx, applicableRes, argCount, argTypes);
  if (ambiguous) {
    ctx.error(
      "Ambiguous overload call: multiple overloads match and none is most specific. Cast an argument to select one.",
      DiagnosticCode.TypeMismatch,
      loc
    );
  }
  for (var i = 0; i < applicableRes.length; i += 1) {
    if (applicableRes[i] == winner) {
      return i;
    }
  }
  return 0;
}

/**
 * The candidates a call's arguments are applicable to: right arity,
 * and every argument assignable to the parameter facing it.
 *
 * `adaptLiterals` selects the second tier of call overload resolution.
 * With it off, each argument is judged by the type it already has in
 * `argTypes`. With it on, an argument whose type is decided by context
 * — a bare numeric literal — is instead judged by whether it *could*
 * be written at the parameter's type, which is what lets
 * `div(someU32, 10)` reach the `(u32, u32)` signature. See the call
 * site for why that is a second tier rather than the only rule.
 *
 * Only the first `callerArgCount` arguments may adapt. Beyond that sit
 * default initializers spliced in from the first-declared signature,
 * which are never re-checked against the signature that wins; letting
 * one of those adapt would select an overload on the strength of
 * another overload's default.
 */
export function collectApplicableOverloads(
  ctx: CheckerContext,
  candidates: GrowableArray<FunctionType>,
  args: GrowableArray<Expression>,
  argTypes: Array<Type>,
  callerArgCount: i32,
  adaptLiterals: boolean
): GrowableArray<FunctionType> {
  let applicable = new Array<FunctionType>();
  for (let candidate in candidates) {
    let expectedCount = candidate.parameters.length;
    var requiredCount = expectedCount;
    let optionals = candidate.optionalParameters;
    if (optionals != null) {
      requiredCount = 0;
      for (let optional in optionals) {
        if (!optional) {
          requiredCount = requiredCount + 1;
        }
      }
    }

    if (args.length >= requiredCount && args.length <= expectedCount) {
      var matchOk = true;
      for (var i = 0; i < args.length && i < expectedCount; i += 1) {
        let param = candidate.parameters[i];
        if (!isAssignableTo(ctx, argTypes[i], param) &&
            !(i < callerArgCount &&
              asyncNeverClosureAdaptsTo(ctx, args[i], argTypes[i], param)) &&
            !(adaptLiterals && i < callerArgCount &&
              argumentAdaptsToParameter(args[i], param))) {
          matchOk = false;
        }
      }
      if (matchOk) {
        applicable.push(candidate);
      }
    }
  }
  return applicable;
}

/**
 * Conservative value-overlap test for the overlap restriction on
 * subclass-added overloads (member-lookup.md §5.1): true when some
 * runtime value could satisfy both types. Exact for class-class
 * (single inheritance: unrelated classes share no subtype) and
 * primitive pairs; conservatively true when interfaces, type
 * parameters, or other open-world types are involved.
 */
function typesMayOverlap(ctx: CheckerContext, a: Type, b: Type): boolean {
  if (isAssignableTo(ctx, a, b) || isAssignableTo(ctx, b, a)) {
    return true;
  }
  return match (a) {
    case UnionT {types}: {
      for (let arm in types) {
        if (typesMayOverlap(ctx, arm, b)) { return true; }
      }
      false
    }
    case _: match (b) {
      case UnionT {types}: {
        for (let arm in types) {
          if (typesMayOverlap(ctx, a, arm)) { return true; }
        }
        false
      }
      case _: {
        let aIsClass = a is ClassType;
        let bIsClass = b is ClassType;
        if (aIsClass && bIsClass) {
          // Unrelated classes (neither assignable) share no common
          // subtype under single inheritance.
          false
        } else if (a is InterfaceType || b is InterfaceType ||
            a is TypeParameterType || b is TypeParameterType) {
          // A class can implement any interface; type parameters are
          // open. Conservatively overlapping.
          true
        } else {
          // Distinct primitives / other closed leaf types with no
          // assignability relation are disjoint.
          false
        }
      }
    }
  };
}

/**
 * True when some argument tuple could be applicable to both
 * signatures: their arity ranges intersect and every shared
 * parameter position may overlap in values.
 */
export function signaturesMayOverlap(
  ctx: CheckerContext,
  a0: FunctionType,
  b: FunctionType
): boolean {
  let a = alignTypeParameters(a0, b);
  var aRequired = a.parameters.length;
  let aOpt = a.optionalParameters;
  if (aOpt != null) {
    aRequired = 0;
    for (let o in aOpt) { if (!o) { aRequired += 1; } }
  }
  var bRequired = b.parameters.length;
  let bOpt = b.optionalParameters;
  if (bOpt != null) {
    bRequired = 0;
    for (let o in bOpt) { if (!o) { bRequired += 1; } }
  }
  let lo = if (aRequired > bRequired) aRequired else bRequired;
  let hiA = a.parameters.length;
  let hiB = b.parameters.length;
  let hi = if (hiA < hiB) hiA else hiB;
  if (lo > hi) {
    return false;
  }
  var i = 0;
  while (i < lo) {
    if (!typesMayOverlap(ctx, a.parameters[i], b.parameters[i])) {
      return false;
    }
    i += 1;
  }
  return true;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19