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

11.9 KiB Raw
/**
 * The rules for contract clauses (docs/design/contracts.md): `requires`
 * and `ensures` on a function, `invariant` on a loop.
 *
 * A clause's condition is an ordinary boolean expression. What differs
 * between the kinds is where on the flow graph the condition is checked,
 * and that an `ensures` condition can name `result` and call `old`.
 */
import { HashSet } from 'zena:collections';
import {
  AssignmentExpression, AwaitExpression, CallExpression, ContractClause,
  ContractKind, ContractMode, Expression, Identifier, Node, Parameter,
  ThisExpression, contractKeyword, isOldCallee,
} from '../ast.zena';
import { DiagnosticCode } from '../diagnostics.zena';
import { FlowNode } from '../analysis/flow.zena';
import { SymbolId } from '../scope/symbol.zena';
import { PurityObligation } from '../semantic-model.zena';
import {
  ErrorType, InlineTupleType, Type, UnionType, VoidType, unwrapAliases
} from '../types.zena';
import { walkEnter } from '../visitor.zena';
import { isInlineType } from './annotations.zena';
import { CheckerContext } from './context.zena';
import { checkExpression, validateConditionType } from './expressions.zena';
import { ConditionNarrowings, conditionNarrowings } from './narrowing.zena';

/**
 * Whether `t` is an inline tuple, or a union of inline tuples: the
 * inline results the lowering lays out as lanes (`inlineLayoutOf`).
 */
function isInlineTupleResult(t: Type): boolean {
  let bare = unwrapAliases(t);
  if (bare is InlineTupleType) { return true; }
  if (let UnionType {types} = bare) {
    for (let member in types) {
      if (!(unwrapAliases(member) is InlineTupleType)) { return false; }
    }
    return true;
  }
  return false;
}

/** Checks one condition as a boolean, and that evaluating it changes nothing. */
function checkCondition(ctx: CheckerContext, clause: ContractClause) {
  let {condition} = clause;
  let conditionType = checkExpression(ctx, condition, null);
  // An error type has been reported where it arose.
  if (!(conditionType is ErrorType)) {
    validateConditionType(ctx, conditionType, condition);
  }
  // A clause can be left out of a build, so a condition that assigns or
  // suspends would make the program behave differently without it.
  let keyword = contractKeyword(clause.kind);
  walkEnter(condition, (n) => {
    if (n is AssignmentExpression) {
      ctx.error(
        `A '${keyword}' condition cannot assign.`,
        DiagnosticCode.InvalidAssignment, n.loc);
    } else if (n is AwaitExpression) {
      ctx.error(
        `A '${keyword}' condition cannot await.`,
        DiagnosticCode.TypeMismatch, n.loc);
    }
  });
  // A `static` condition is never run, so it can stand for a fact only
  // if evaluating it would change nothing. That depends on the bodies
  // of what it calls, and is settled when every module is checked.
  if (clause.mode == ContractMode.Static && !(conditionType is ErrorType)) {
    ctx.model.addPurityObligation(new PurityObligation(
      condition, `A 'static ${keyword}' condition`, clause.kind == ContractKind.Ensures
    ));
  }
}

/**
 * Checks a function's `requires` clauses. Called at the start of the
 * body's flow, with the parameters bound: a precondition sees what the
 * body sees on entry.
 *
 * A precondition is checked on every call, and a call that fails it
 * does not reach the body. So what a condition narrows when it is true
 * holds from there on: each clause leaves its narrowings on the flow
 * for the clauses after it and for the body, as the test of an `if`
 * does for its consequent.
 *
 * Returns the flow position to check the function's postconditions
 * from (checkEnsuresClauses). That is the entry plus the narrowings on
 * parameters, which cannot be reassigned, so those still hold on the
 * way out. Narrowings on member paths are left out: a path can start
 * at a variable the body assigns.
 */
export function checkRequiresClauses(
  ctx: CheckerContext,
  contracts: GrowableArray<ContractClause> | null,
  params: GrowableArray<Parameter>
): FlowNode {
  let entryFlow = ctx.currentFlow;
  if (contracts == null) { return entryFlow; }
  let parameterIds = new HashSet<SymbolId>();
  for (let param in params) {
    let parameter = ctx.model.resolveDeclaration(param);
    if (parameter != null) { parameterIds.add(parameter.id); }
  }
  let onParameters = new ConditionNarrowings();
  for (let clause in contracts) {
    if (clause.kind != ContractKind.Requires) { continue; }
    checkCondition(ctx, clause);
    // A `debug` clause is left out of some builds, and a `static` one of
    // every build, so nothing after them can rely on what they would
    // have narrowed.
    if (clause.mode != ContractMode.Checked) { continue; }
    let narrowings = conditionNarrowings(ctx, clause.condition).whenTrue;
    ctx.pushFlowNarrowings(narrowings);
    // A later clause narrows what an earlier one left, so its type for
    // a parameter replaces the earlier one.
    for (let id in narrowings.bindings.keys()) {
      if (parameterIds.has(id)) {
        onParameters.bindings[id] = narrowings.bindings[id];
      }
    }
  }
  let bodyFlow = ctx.currentFlow;
  ctx.setFlow(entryFlow);
  ctx.pushFlowNarrowings(onParameters);
  let ensuresFlow = ctx.currentFlow;
  ctx.setFlow(bodyFlow);
  return ensuresFlow;
}

/**
 * Reports `this` in a constructor's `requires` conditions. They run
 * ahead of the field initializers, before the object exists.
 */
export function rejectThisInRequires(
  ctx: CheckerContext,
  contracts: GrowableArray<ContractClause> | null
): void {
  if (contracts == null) { return; }
  for (let clause in contracts) {
    if (clause.kind != ContractKind.Requires) { continue; }
    walkEnter(clause.condition, (n) => {
      if (n is ThisExpression) {
        ctx.error(
          "A constructor's 'requires' condition cannot use 'this': it runs before the object exists.",
          DiagnosticCode.TypeMismatch, n.loc);
      }
    });
  }
}

/**
 * Checks a function's `ensures` clauses. Called after the body, when
 * an inferred return type is known, with `resultType` the type a
 * `return` hands back: for an `async` function, the value its future
 * completes with, and for a generator, nothing.
 *
 * `entryFlow` is the flow position checkRequiresClauses returned. A
 * postcondition holds on every path out of the body, so nothing one of
 * those paths narrowed is known in it, and it is checked from the
 * entry.
 */
export function checkEnsuresClauses(
  ctx: CheckerContext,
  contracts: GrowableArray<ContractClause> | null,
  params: GrowableArray<Parameter>,
  resultType: Type,
  entryFlow: FlowNode,
  isGenerator: boolean = false
): void {
  if (contracts == null) { return; }
  // An inline tuple result is returned as several values, and `result`
  // is bound to them as an inline parameter is. An inline record, or a
  // union mixing an inline tuple with anything else, has no such
  // binding yet (#932).
  if (isInlineType(resultType) && !isInlineTupleResult(resultType)) {
    rejectEnsuresClauses(ctx, contracts, 'a function that returns an inline record');
    return;
  }
  var reportedParameter = false;
  for (let clause in contracts) {
    if (clause.kind != ContractKind.Ensures) { continue; }
    if (!reportedParameter) {
      reportedParameter = true;
      for (let param in params) {
        if (param.name.name == 'result') {
          ctx.error(
            "A parameter named 'result' cannot be read in an 'ensures' condition, " +
            "where 'result' is the returned value. Rename the parameter.",
            DiagnosticCode.DuplicateDeclaration, param.name.loc);
        }
      }
    }
    let resultSymbol = ctx.model.resolveDeclaration(clause);
    let returnsNothing = resultType is VoidType;
    if (resultSymbol != null) {
      ctx.declareBinding(resultSymbol, if (returnsNothing) new ErrorType() else resultType);
      if (returnsNothing) {
        walkEnter(clause.condition, (n) => {
          if (n is Identifier && ctx.model.resolve(n) === resultSymbol) {
            // A generator's call returns its iterator; its body, which
            // the postcondition follows, returns nothing.
            ctx.error(
              if (isGenerator) {
                "'result' has no value here: a generator's body returns nothing."
              } else {
                "'result' has no value here: the function returns nothing."
              },
              DiagnosticCode.TypeMismatch, n.loc);
          }
        });
      }
    }
    ctx.setFlow(entryFlow);
    ctx.setInEnsures(true);
    checkCondition(ctx, clause);
    ctx.setInEnsures(false);
  }
}

/**
 * Checks a loop's `invariant` clauses. Called inside the loop's flow,
 * ahead of its condition: an invariant holds each time the loop is
 * about to test whether to run again.
 */
export function checkLoopInvariants(
  ctx: CheckerContext,
  invariants: GrowableArray<ContractClause> | null
): void {
  if (invariants == null) { return; }
  for (let clause in invariants) {
    checkCondition(ctx, clause);
  }
}

/** Reports the `ensures` clauses of a function that cannot have any yet. */
export function rejectEnsuresClauses(
  ctx: CheckerContext,
  contracts: GrowableArray<ContractClause> | null,
  where: String
): void {
  if (contracts == null) { return; }
  for (let clause in contracts) {
    if (clause.kind == ContractKind.Ensures) {
      ctx.errorOnceAt(
        `'ensures' clauses on ${where} are not supported yet.`,
        DiagnosticCode.TypeMismatch, clause.loc);
    }
  }
}

/** Reports the clauses of a function that cannot have any yet. */
export function rejectContracts(
  ctx: CheckerContext,
  contracts: GrowableArray<ContractClause> | null,
  where: String
): void {
  if (contracts == null) { return; }
  for (let clause in contracts) {
    ctx.errorOnceAt(
      `'${contractKeyword(clause.kind)}' clauses on ${where} are not supported yet.`,
      DiagnosticCode.TypeMismatch, clause.loc);
  }
}

/**
 * The type of `old(e)`, or null when `call` is an ordinary call.
 * `old(e)` is `e`'s value when the function was entered, so it has
 * `e`'s type, and `e` can name only what exists on entry.
 */
export function checkOldExpression(ctx: CheckerContext, call: CallExpression): Type | null {
  if (!isOldCallee(call.callee) || !(ctx.inEnsures || ctx.inOld)) { return null; }
  if (ctx.inOld) {
    ctx.error("'old' cannot be used inside another 'old'.", DiagnosticCode.TypeMismatch, call.loc);
    return new ErrorType();
  }
  // A constructor is entered before its object exists, and its
  // postconditions run in a different compiled function from its entry.
  if (ctx.inConstructor) {
    ctx.error(
      "'old' in a constructor's 'ensures' condition is not supported yet.",
      DiagnosticCode.TypeMismatch, call.loc);
    return new ErrorType();
  }
  if (call.args.length != 1 || call.typeArguments != null) {
    ctx.error(
      "'old' takes one expression: 'old(e)' is the value 'e' had when the function was entered.",
      DiagnosticCode.ArgumentCountMismatch, call.loc);
    return new ErrorType();
  }
  let argument = call.args[0];
  ctx.setInEnsures(false);
  ctx.setInOld(true);
  let argumentType = checkExpression(ctx, argument, null);
  ctx.setInOld(false);
  ctx.setInEnsures(true);
  // The value is kept from entry as one value; an inline one is several.
  if (isInlineType(argumentType)) {
    ctx.error(
      "'old' of an inline value is not supported yet.",
      DiagnosticCode.TypeMismatch, call.loc);
    return new ErrorType();
  }
  walkEnter(argument, (n) => {
    if (n is Identifier) {
      let named = ctx.model.resolve(n);
      if (named != null && named.declaration is ContractClause) {
        ctx.error(
          "'result' cannot be used inside 'old': it has no value when the function is entered.",
          DiagnosticCode.TypeMismatch, n.loc);
      }
    }
  });
  // The argument runs on entry in a build that checks the clause and
  // not at all in one that leaves it out, so it can change nothing.
  if (!(argumentType is ErrorType)) {
    ctx.model.addPurityObligation(new PurityObligation(argument, "The argument of 'old'", false));
  }
  return argumentType;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19