A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file frontend.ts
* @brief TypeScript AST -> EIR-high.
*
* @details Uses the real `typescript` program and checker. Re-implementing TS
* inference is the one decision that would sink this project.
*
* The SDK entry points are INTRINSICS, not calls: `defineSystem`,
* `Query`, `Mut`, `Res`, `defineComponent`. `defineComponent('Mover',
* {...})` is runtime reflection, and AOT needs it to be a compile-time
* declaration — so both arguments must be literals or the file falls
* back to the interpreter.
*
* NOTHING in this file may call `getText()`, `getSourceFile()` or read
* `.parent`. Those need the program to have BOUND, which only happens
* as a side effect of getTypeChecker(); they have already broken line
* numbers, binding resolution, operator text and parameter names here.
* Use `.text` on an identifier and `ts.tokenToString(kind)` on a token.
*
* Nothing here throws on code it cannot handle. Anything outside the
* subset produces a Diagnostic naming the line and the reason, and its
* system is simply not compiled. Falling back rather than failing is
* what lets this ship before it is finished.
*/
import { sep } from 'node:path';
import ts from 'typescript';
import { resourceMethodBit } from '../../sdk/src/ecs/resourceShapes';
import {
BOOL, ENTITY, F64, HOST_ENC,
type CompShape, type EirModule, type EirSystem, type EirType,
EXACT_FNS, MATH_CONSTS, MATH_FNS,
type FieldSpec, type EirFn, type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp, type LogicOp,
type MathFn,
} from './eir';
export interface Diagnostic {
readonly file: string;
readonly line: number;
readonly message: string;
readonly kind: RefusalKind;
/**
* Whether the author PROMISED this would compile. `@compiled` on a system
* makes its refusal an error: without the marker a system that quietly stops
* compiling just gets slower, and nothing anywhere goes red.
*/
readonly severity: 'error' | 'note';
/** The system this killed, when the failure happened inside one. */
readonly system?: string;
}
export interface LowerResult {
readonly module: EirModule;
readonly diagnostics: readonly Diagnostic[];
/** Systems seen, whether or not they compiled — the coverage gate's denominator. */
readonly seen: readonly string[];
/**
* The `const` each system is bound to -> its declared name. Registration in
* main.ts names the BINDING, so this is what lets a caller ask whether a
* system runs per frame or once at startup.
*/
readonly systemBindings: ReadonlyMap<string, string>;
/**
* Systems the author marked `@compiled`. Compiling these is a PROMISE, and
* `brokenPromises` is what a build asks whether it was kept.
*/
readonly required: readonly string[];
}
/**
* A `@compiled` tag, read straight off the parse tree. `ts.getJSDocTags` walks
* parent pointers, which this file may not touch (see the header); `node.jsDoc`
* is what the parser attached and needs nothing bound.
*/
interface WithJsDoc {
readonly jsDoc?: readonly ts.JSDoc[];
}
function marksCompiled(node: ts.Node): boolean {
const doc = (node as WithJsDoc).jsDoc;
if (!doc) return false;
return doc.some((d) => d.tags?.some((t) => t.tagName.text === 'compiled') ?? false);
}
/**
* The promises this program did not keep: every marked system that refused, plus
* any that vanished without a diagnostic. A build fails on this list; an unmarked
* refusal stays a note, because falling back to the interpreter is a design
* and not a defect.
*/
export function brokenPromises(result: LowerResult): readonly Diagnostic[] {
const compiled = new Set(result.module.systems.map((s) => s.name));
const spoken = new Set<string>();
const out = result.diagnostics.filter((d) => {
if (d.severity !== 'error') return false;
if (d.system) spoken.add(d.system);
return true;
});
for (const name of result.required) {
if (compiled.has(name) || spoken.has(name)) continue;
out.push({
file: '', line: 0, kind: 'pending', severity: 'error', system: name,
message: `'${name}' is marked @compiled but the compiler never produced it`,
});
}
return out;
}
const BIN_OPS: ReadonlyMap<ts.SyntaxKind, BinOp> = new Map([
[ts.SyntaxKind.PlusToken, '+'], [ts.SyntaxKind.MinusToken, '-'],
[ts.SyntaxKind.AsteriskToken, '*'], [ts.SyntaxKind.SlashToken, '/'],
[ts.SyntaxKind.PercentToken, '%'],
[ts.SyntaxKind.LessThanToken, '<'], [ts.SyntaxKind.LessThanEqualsToken, '<='],
[ts.SyntaxKind.GreaterThanToken, '>'], [ts.SyntaxKind.GreaterThanEqualsToken, '>='],
[ts.SyntaxKind.EqualsEqualsEqualsToken, '=='], [ts.SyntaxKind.ExclamationEqualsEqualsToken, '!='],
] as const);
const COMPOUND: ReadonlyMap<ts.SyntaxKind, BinOp> = new Map([
[ts.SyntaxKind.PlusEqualsToken, '+'], [ts.SyntaxKind.MinusEqualsToken, '-'],
[ts.SyntaxKind.AsteriskEqualsToken, '*'], [ts.SyntaxKind.SlashEqualsToken, '/'],
] as const);
const LOGIC_OPS: ReadonlyMap<ts.SyntaxKind, LogicOp> = new Map([
[ts.SyntaxKind.AmpersandAmpersandToken, '&&'],
[ts.SyntaxKind.BarBarToken, '||'],
] as const);
/**
* A token's source text WITHOUT touching the node. `getText()` walks parent
* pointers, which exist only after the program has bound — the same trap that
* has now caught line numbers, binding resolution and this.
*/
function tokenText(kind: ts.SyntaxKind): string {
return ts.tokenToString(kind) ?? ts.SyntaxKind[kind];
}
/**
* Command records this subset emits, and how many arguments each carries.
* `spawn` is absent on purpose: it returns a builder that the corpus chains
* `.insert(Component, {…})` onto, which needs component literals as values.
*/
const COMMAND_RECORDS: Record<string, number | undefined> = { despawn: 1 };
/**
* A module-level `const` the compiler can read at compile time: a literal, or a
* record of them. `WORLD_HALF_W` and `FOLLOW.damping` are values, not storage,
* so a system reading one gets a constant rather than a load.
*/
export type ConstValue = number | boolean | { readonly [k: string]: ConstValue };
/** `const X = 800` / `const F = { damping: 5 }` -> a value, or null if not literal. */
function constValue(node: ts.Expression): ConstValue | null {
if (ts.isNumericLiteral(node)) return Number(node.text);
if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
const inner = constValue(node.operand);
return typeof inner === 'number' ? -inner : null;
}
if (ts.isObjectLiteralExpression(node)) {
const out: Record<string, ConstValue> = {};
for (const prop of node.properties) {
if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return null;
const v = constValue(prop.initializer);
if (v === null) return null;
out[prop.name.text] = v;
}
return out;
}
return null;
}
/** `number` / `boolean` written as an annotation; nothing else is a subset type. */
function annotatedType(node: ts.TypeNode): EirType | null {
if (node.kind === ts.SyntaxKind.NumberKeyword) return F64;
if (node.kind === ts.SyntaxKind.BooleanKeyword) return BOOL;
return null;
}
/** A string or integer literal argument, or null when it is neither. */
function literalKey(node: ts.Expression | undefined): string | number | null {
if (!node) return null;
if (ts.isStringLiteral(node)) return node.text;
if (ts.isNumericLiteral(node)) return Number(node.text);
return null;
}
/**
* `permanent` = the contract has no place for it, not a
* todo. `pending` = the contract admits it, nobody lowered it yet. Default is
* `pending`; every `permanent` below names what is missing.
*/
export type RefusalKind = 'permanent' | 'pending';
/** Thrown internally to abandon one system; never escapes lowerProgram. */
class NotInSubset extends Error {
constructor(
readonly node: ts.Node,
message: string,
readonly kind: RefusalKind = 'pending',
) { super(message); }
}
class SystemLowerer {
private readonly locals: Local[] = [];
private next = 0;
/** A stack, not one map: a `const` in a row loop must not outlive the loop. */
private readonly scopes: Map<string, Local>[] = [new Map()];
/** Depth inside a `res.modify` body, where writing the resource is the point. */
private inModify = 0;
constructor(
private readonly comps: Map<string, CompShape>,
/** `const Speed = defineComponent('FixtureSpeed', …)` — a query names the
* BINDING, and the shape is filed under the declared name. */
private readonly bindings: ReadonlyMap<string, string>,
/** Module-level literals, folded where they are read. */
private readonly consts: ReadonlyMap<string, ConstValue>,
/** Module-level pure functions, callable from a system or from each other. */
private readonly fns: ReadonlyMap<string, EirFn>,
/** Why a function is absent, so the call site can say more than "no". */
private readonly fnFailures: ReadonlyMap<string, string> = new Map(),
/** Event payloads by declared name, and the const each is bound to. */
private readonly events: ReadonlyMap<string, CompShape> = new Map(),
private readonly eventBindings: ReadonlyMap<string, string> = new Map(),
/** Events with no payload VALUE beside their type. Compiled code reads a
* payload by position, and only the value tells the runtime which
* position is which. */
private readonly unpayloaded: ReadonlySet<string> = new Set(),
) {}
/** The event a binding names, or null when the program declares no such one. */
private eventName(binding: string): string | null {
const name = this.eventBindings.get(binding) ?? binding;
return this.events.has(name) ? name : null;
}
/** Lower a module-level function; `lower` does the same for a system body. */
lowerFn(name: string, params: readonly ts.ParameterDeclaration[], body: ts.ConciseBody): EirFn {
const bound = params.map((p) => {
if (!ts.isIdentifier(p.name)) throw new NotInSubset(p, 'a parameter must be a plain name');
if (!p.type) {
throw new NotInSubset(p, `parameter '${p.name.text}' needs a type annotation`);
}
const t = annotatedType(p.type);
if (!t) throw new NotInSubset(p.type, 'a parameter must be annotated number or boolean');
return this.define(p.name.text, t);
});
// One `return <expr>` and nothing else: that is what makes inlining a
// substitution rather than a control-flow splice, and it covers the
// numeric helpers the corpus writes.
const value = ts.isBlock(body)
? (() => {
const only = body.statements.length === 1 ? body.statements[0] : undefined;
if (!only || !ts.isReturnStatement(only) || !only.expression) {
throw new NotInSubset(body, 'a function body must be a single return of an expression');
}
return this.expr(only.expression);
})()
: this.expr(body);
const paramIds = new Set(bound.map((b) => b.id));
return {
name,
params: bound,
locals: this.locals.filter((l) => !paramIds.has(l.id)),
body: [{ s: 'return', value }],
ret: value.type,
};
}
/** The constant a dotted path names, or null when the root is not one. */
private constAt(root: string, path: readonly string[]): ConstValue | null {
let cur = this.consts.get(root);
if (cur === undefined) return null;
for (const key of path) {
if (cur === null || typeof cur !== 'object') return null;
cur = (cur as Record<string, ConstValue>)[key];
if (cur === undefined) return null;
}
return cur;
}
private compName(binding: string): string {
return this.bindings.get(binding) ?? binding;
}
private define(name: string, type: EirType): Local {
const l: Local = { id: this.next++, name, type };
this.locals.push(l);
this.scopes[this.scopes.length - 1]!.set(name, l);
return l;
}
/** The local a name binds to, or null — for a caller that wants to ask, not throw. */
private tryLookup(name: string): Local | null {
for (let i = this.scopes.length - 1; i >= 0; i--) {
const l = this.scopes[i]!.get(name);
if (l) return l;
}
return null;
}
private lookup(node: ts.Node, name: string): Local {
for (let i = this.scopes.length - 1; i >= 0; i--) {
const l = this.scopes[i]!.get(name);
if (l) return l;
}
// Some of these are heap values (an array, a class) and some are not —
// a numeric enum member is a compile-time constant nobody folds yet. The
// default stands: claiming it cannot be done needs a reason.
throw new NotInSubset(node, `'${name}' is not a value this system declared`);
}
private scoped<T>(fn: () => T): T {
this.scopes.push(new Map());
try { return fn(); } finally { this.scopes.pop(); }
}
/** `[Query(Mut(Transform), Mover), Res(Time)]` -> one param type each. */
private paramTypes(node: ts.Expression): EirType[] {
if (!ts.isArrayLiteralExpression(node)) {
throw new NotInSubset(node, "defineSystem's parameter list must be an array literal");
}
return node.elements.map((el) => {
if (!ts.isCallExpression(el) || !ts.isIdentifier(el.expression)) {
throw new NotInSubset(el, 'each parameter must be Query(...) or Res(...)');
}
const kind = el.expression.text;
if (kind === 'Res' || kind === 'ResMut') {
const arg = el.arguments[0];
if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, `${kind}(...) needs a named resource`);
return { k: 'res', name: this.compName(arg.text), mut: kind === 'ResMut' } as EirType;
}
if (kind === 'EventWriter' || kind === 'EventReader') {
const arg = el.arguments[0];
if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, `${kind}(...) needs a named event`);
const name = this.eventName(arg.text);
if (!name) {
throw new NotInSubset(el, `'${arg.text}' is not an event this program declares`);
}
if (this.unpayloaded.has(name)) {
throw new NotInSubset(el, `'${name}' is declared without a payload value, so nothing`
+ ' at run time can say which field a compiled system read. Give defineEvent a'
+ ` default: defineEvent<...>('${name}', { ... })`, 'permanent');
}
return kind === 'EventWriter'
? { k: 'channel', name, channel: 'event' } as EirType
: { k: 'events', name } as EirType;
}
if (kind === 'Commands') {
if (el.arguments.length !== 0) throw new NotInSubset(el, 'Commands() takes no arguments');
return { k: 'channel', name: 'Commands', channel: 'commands' } as EirType;
}
if (kind !== 'Query') {
// GetWorld hands over the whole World — arbitrary access, the one
// thing a closed contract cannot have. The rest are parameters
// nobody has lowered yet.
throw new NotInSubset(el, `'${kind}' is not a parameter intrinsic`,
kind === 'GetWorld' ? 'permanent' : 'pending');
}
const args: QueryArg[] = el.arguments.map((a) => this.queryArg(a));
return { k: 'query', args } as EirType;
});
}
private queryArg(node: ts.Expression): QueryArg {
if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
if (node.expression.text !== 'Mut') {
throw new NotInSubset(node, `'${node.expression.text}(...)' is not a query argument this subset lowers`);
}
const inner = node.arguments[0];
if (!inner || !ts.isIdentifier(inner)) throw new NotInSubset(node, 'Mut(...) needs a named component');
return { comp: this.compName(inner.text), mut: true };
}
if (!ts.isIdentifier(node)) throw new NotInSubset(node, 'a query argument must be a named component');
return { comp: this.compName(node.text), mut: false };
}
lower(name: string, params: ts.Expression, fn: ts.ArrowFunction): EirSystem {
const types = this.paramTypes(params);
if (fn.parameters.length !== types.length) {
throw new NotInSubset(fn, `the callback takes ${fn.parameters.length} parameters but ${types.length} were declared`);
}
const bound: Local[] = fn.parameters.map((p, i) => {
if (!ts.isIdentifier(p.name)) throw new NotInSubset(p, 'a system parameter must be a plain name');
return this.define(p.name.text, types[i]!);
});
const body = ts.isBlock(fn.body)
? fn.body.statements.flatMap((s) => this.stmt(s))
: (() => { throw new NotInSubset(fn, 'the callback must have a block body'); })();
const paramIds = new Set(bound.map((b) => b.id));
return {
name,
params: bound,
locals: this.locals.filter((l) => !paramIds.has(l.id)),
body,
};
}
private stmt(node: ts.Statement): Stmt[] {
if (ts.isForOfStatement(node)) return [this.rowLoop(node)];
if (ts.isExpressionStatement(node)) {
if (ts.isCallExpression(node.expression)) return this.callStmt(node.expression);
return [this.assignment(node.expression)];
}
if (ts.isBlock(node)) return this.scoped(() => node.statements.flatMap((s) => this.stmt(s)));
if (ts.isVariableStatement(node)) return this.declarations(node);
if (ts.isIfStatement(node)) return [this.ifStmt(node)];
// A bare `return` leaves the SYSTEM; one with a value belongs to a
// module function, which `fn()` lowers on its own.
if (ts.isReturnStatement(node)) {
if (node.expression) throw new NotInSubset(node, 'a system returns no value');
return [{ s: 'return', value: null }];
}
if (ts.isContinueStatement(node)) {
if (node.label) throw new NotInSubset(node, 'a labelled continue is not lowered');
return [{ s: 'continue' }];
}
if (ts.isBreakStatement(node)) {
if (node.label) throw new NotInSubset(node, 'a labelled break is not lowered');
return [{ s: 'break' }];
}
throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not a statement this subset lowers`);
}
/** `const x = expr` — the local takes the initializer's type; there is none to declare. */
private declarations(node: ts.VariableStatement): Stmt[] {
return node.declarationList.declarations.map((d) => {
if (!ts.isIdentifier(d.name)) throw new NotInSubset(d, 'a declaration must bind a plain name');
if (!d.initializer) throw new NotInSubset(d, 'a local must be initialized where it is declared');
const value = this.expr(d.initializer);
if (value.type.k !== 'f64' && value.type.k !== 'bool') {
// A component or query is a reference, and the contract has no
// reference values — only memory it was handed, and numbers.
throw new NotInSubset(d, `a local cannot hold a ${value.type.k}`, 'permanent');
}
return { s: 'let', id: this.define(d.name.text, value.type).id, value } as Stmt;
});
}
private ifStmt(node: ts.IfStatement): Stmt {
const cond = this.expr(node.expression);
if (cond.type.k !== 'bool') throw new NotInSubset(node.expression, 'an if condition must be a boolean');
const then = this.scoped(() => this.stmt(node.thenStatement));
const otherwise = node.elseStatement ? this.scoped(() => this.stmt(node.elseStatement!)) : [];
return { s: 'if', cond, then, otherwise };
}
/** `for (const [e, a, b] of query) { ... }` — the shape a system iterates rows in. */
private rowLoop(node: ts.ForOfStatement): Stmt {
if (!ts.isIdentifier(node.expression)) {
throw new NotInSubset(node.expression, 'a row loop must iterate a declared query');
}
const q = this.lookup(node.expression, node.expression.text);
const qt = q.type;
// An event reader yields ONE payload per step, so it binds a plain name
// rather than destructuring a row of components.
if (qt.k === 'events') return this.eventLoop(node, q, qt.name);
if (qt.k !== 'query') throw new NotInSubset(node.expression, `'${q.name}' is not a query`);
const decl = ts.isVariableDeclarationList(node.initializer) ? node.initializer.declarations[0] : undefined;
if (!decl || !decl.name || !ts.isArrayBindingPattern(decl.name)) {
throw new NotInSubset(node, 'a row loop must destructure [entity, ...components]');
}
// A destructuring may bind a PREFIX and may elide holes — `[, transform,
// player]` is what most of the corpus writes. Demanding one name per
// yielded value refused legal TypeScript for no reason.
const elements = decl.name.elements;
if (elements.length > qt.args.length + 1) {
throw new NotInSubset(node, `the row binds ${elements.length} names but the query yields ${qt.args.length + 1}`);
}
let entity: number | null = null;
const binds: number[] = [];
elements.forEach((el, i) => {
if (ts.isOmittedExpression(el)) {
// A hole still occupies its position; the row just does not name it.
if (i > 0) binds.push(this.define(`_hole${i}`, { k: 'comp', name: qt.args[i - 1]!.comp }).id);
return;
}
if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name)) {
throw new NotInSubset(el, 'a row binding must be a plain name');
}
const nm = el.name.text;
if (i === 0) {
const l = this.define(nm, ENTITY);
// A row's entity is bound whether or not the body reads it; the
// leading underscore convention only says the author expects not to.
entity = l.id;
return;
}
const arg = qt.args[i - 1]!;
binds.push(this.define(nm, { k: 'comp', name: arg.comp }).id);
});
// A prefix binding still needs the trailing components bound, because the
// interpreter and every later pass index binds positionally.
for (let i = elements.length; i < qt.args.length + 1; i++) {
binds.push(this.define(`_tail${i}`, { k: 'comp', name: qt.args[i - 1]!.comp }).id);
}
const body = this.scoped(() => (ts.isBlock(node.statement)
? node.statement.statements.flatMap((s) => this.stmt(s))
: this.stmt(node.statement)));
return { s: 'rowLoop', query: { p: 'local', id: q.id }, entity, binds, body };
}
/**
* A call statement: `res.modify(fn)`, which is inlined, or a channel emit.
*
* `ResMut` is the one parameter whose SOURCE FORM differs by road: the
* interpreter hands a WRAPPER, so `r.n = 1` sets a field of it and the world
* never sees the write. `.modify` is the spelling both roads take.
*/
private callStmt(node: ts.CallExpression): Stmt[] {
const callee = node.expression;
if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)
&& callee.name.text === 'modify') {
const target = this.tryLookup(callee.expression.text);
if (target !== null && target.type.k === 'res') return this.modify(node, target);
}
return [this.emit(node)];
}
/**
* `res.modify((v) => { ... })`, inlined with `v` bound to the resource.
*
* An ALIAS, not a copy: the body addresses exactly what `res.field` would,
* so one authored line becomes one write on either road.
*/
private modify(node: ts.CallExpression, target: Local): Stmt[] {
if (target.type.k !== 'res' || !target.type.mut) {
throw new NotInSubset(node, `'${target.name}' is a Res; only a ResMut can be modified`);
}
const fn = node.arguments[0];
if (fn === undefined || node.arguments.length !== 1 || !ts.isArrowFunction(fn)) {
throw new NotInSubset(node, 'modify takes exactly one arrow function');
}
if (fn.parameters.length !== 1) {
throw new NotInSubset(node,
`modify's callback takes 1 parameter, not ${fn.parameters.length}`);
}
const name = fn.parameters[0]!.name;
if (!ts.isIdentifier(name)) {
throw new NotInSubset(node, "modify's parameter must be a plain name");
}
this.inModify++;
try {
return this.scoped(() => {
this.scopes[this.scopes.length - 1]!.set(name.text, target);
return ts.isBlock(fn.body)
? fn.body.statements.flatMap((st) => this.stmt(st))
: [this.assignment(fn.body)];
});
} finally {
this.inModify--;
}
}
/**
* `cmds.despawn(entity)` — a record appended to a channel, not a call. The
* SDK already defers these to a flush at system end, so this models what it
* does rather than pretending the mutation happens here.
*/
private emit(node: ts.CallExpression): Stmt {
const callee = node.expression;
if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)) {
throw new NotInSubset(node, 'a call statement must be a method on a declared channel');
}
const target = this.lookup(callee.expression, callee.expression.text);
if (target.type.k !== 'channel') {
throw new NotInSubset(node, `'${target.name}' is not a channel this subset can emit to`);
}
const record = callee.name.text;
if (target.type.channel === 'event') {
if (record !== 'send') {
throw new NotInSubset(node, `an event writer has only 'send', not '${record}'`);
}
return this.sendEvent(node, target, target.type.name);
}
const arity = COMMAND_RECORDS[record];
if (arity === undefined) {
throw new NotInSubset(node, `Commands.${record} is not a record this subset emits yet`);
}
if (node.arguments.length !== arity) {
throw new NotInSubset(node, `Commands.${record} takes ${arity} argument(s), not ${node.arguments.length}`);
}
const args = node.arguments.map((a) => this.expr(a));
return { s: 'emit', channel: { p: 'local', id: target.id }, record, args };
}
/**
* `for (const blow of blows)` over an `EventReader`. One binding, no entity:
* an event is a payload rather than a row of components, and the loop is
* the same statement so every later pass walks one shape.
*/
private eventLoop(node: ts.ForOfStatement, reader: Local, event: string): Stmt {
const decl = ts.isVariableDeclarationList(node.initializer)
? node.initializer.declarations[0] : undefined;
if (!decl || !decl.name || !ts.isIdentifier(decl.name)) {
throw new NotInSubset(node, 'an event loop binds one plain name');
}
const bindingName = decl.name.text;
return this.scoped(() => {
const bound = this.define(bindingName, { k: 'comp', name: event });
const body = ts.isBlock(node.statement)
? node.statement.statements.flatMap((st) => this.stmt(st))
: this.stmt(node.statement);
return { s: 'rowLoop', query: { p: 'local', id: reader.id }, entity: null, binds: [bound.id], body };
});
}
/**
* `writer.send({ target: e, amount: 3 })` — the payload is FLATTENED into
* the fields the event declares, in that order, so nothing needs a heap.
* A field the event does not declare, or one it declares and the literal
* omits, is refused: the record's shape is the contract.
*/
private sendEvent(node: ts.CallExpression, writer: Local, event: string): Stmt {
const arg = node.arguments[0];
if (node.arguments.length !== 1 || !arg || !ts.isObjectLiteralExpression(arg)) {
throw new NotInSubset(node, 'send takes one object literal');
}
const shape = this.events.get(event);
if (!shape) throw new NotInSubset(node, `'${event}' has no declared payload`);
const given = new Map<string, ts.Expression>();
const collect = (obj: ts.ObjectLiteralExpression, prefix: string): void => {
for (const prop of obj.properties) {
if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) {
throw new NotInSubset(prop, 'a payload field must be `name: value`');
}
const path = prefix ? `${prefix}.${prop.name.text}` : prop.name.text;
if (ts.isObjectLiteralExpression(prop.initializer)) {
collect(prop.initializer, path);
continue;
}
given.set(path, prop.initializer);
}
};
collect(arg, '');
const args: Expr[] = [];
for (const field of shape.fields.keys()) {
const value = given.get(field);
if (!value) throw new NotInSubset(node, `send is missing '${field}' of event '${event}'`);
args.push(this.expr(value));
given.delete(field);
}
const extra = [...given.keys()][0];
if (extra) throw new NotInSubset(node, `event '${event}' has no field '${extra}'`);
return { s: 'emit', channel: { p: 'local', id: writer.id }, record: 'send', args };
}
private assignment(node: ts.Expression): Stmt {
if (!ts.isBinaryExpression(node)) {
throw new NotInSubset(node, 'only assignments are statements in this subset');
}
const compound = COMPOUND.get(node.operatorToken.kind);
const target = this.place(node.left);
this.refuseBareResourceWrite(node.left, target);
if (compound) {
const type = this.placeType(node.left);
const read: Expr = { e: 'read', place: target, type };
const r = this.expr(node.right);
return { s: 'assign', target, value: { e: 'bin', op: compound, l: read, r, type } };
}
if (node.operatorToken.kind !== ts.SyntaxKind.EqualsToken) {
throw new NotInSubset(node, `'${tokenText(node.operatorToken.kind)}' is not an assignment this subset lowers`);
}
// Resolved for its REFUSALS: a plain `=` needs no read, so a field no
// declared shape has reached the IR verifier rather than being refused
// here, which coverage.test.ts calls a frontend bug.
this.placeType(node.left);
return { s: 'assign', target, value: this.expr(node.right) };
}
/**
* A write straight into a resource, outside `modify`, is refused.
*
* One line, two meanings: this side lowers a write, and the interpreter sets
* a field on the ResMut WRAPPER that no reader of the world sees.
*/
private refuseBareResourceWrite(node: ts.Expression, target: Place): void {
if (this.inModify > 0) return;
let base = target;
while (base.p === 'field') base = base.base;
const local = this.locals.find((l) => l.id === base.id);
if (local?.type.k !== 'res') return;
throw new NotInSubset(node, `'${local.name}' is a resource, and a bare write to one is a `
+ 'no-op in the interpreter — write it as '
+ `${local.name}.modify((v) => { ... }), which both roads lower the same`);
}
/** A place is a local, or a dotted path from one. Nothing else is addressable. */
private place(node: ts.Expression): Place {
if (ts.isIdentifier(node)) {
if (this.consts.has(node.text) && !this.scopes.some((sc) => sc.has(node.text))) {
throw new NotInSubset(node, `'${node.text}' is a constant and cannot be assigned`);
}
return { p: 'local', id: this.lookup(node, node.text).id };
}
if (!ts.isPropertyAccessExpression(node)) {
throw new NotInSubset(node, 'only a name or a dotted path can be read or assigned here');
}
const path: string[] = [];
let cur: ts.Expression = node;
while (ts.isPropertyAccessExpression(cur)) {
path.unshift(cur.name.text);
cur = cur.expression;
}
if (!ts.isIdentifier(cur)) throw new NotInSubset(node, 'a dotted path must start at a declared name');
if (this.consts.has(cur.text) && !this.scopes.some((sc) => sc.has(cur.text))) {
throw new NotInSubset(node, `'${cur.text}' is a constant and cannot be assigned`);
}
return { p: 'field', base: { p: 'local', id: this.lookup(cur, cur.text).id }, path };
}
/**
* The type a place reads as. A component or resource field must exist in the
* declared shape — this is where a typo stops being a runtime undefined.
*/
private placeType(node: ts.Expression): EirType {
const place = this.place(node);
if (place.p === 'local') {
return this.locals.find((l) => l.id === place.id)!.type;
}
const base = this.locals.find((l) => l.id === (place.base as { p: 'local'; id: number }).id)!;
const key = place.path.join('.');
if (base.type.k === 'comp') {
const shape = this.comps.get(base.type.name);
if (!shape) throw new NotInSubset(node, `no declared shape for component '${base.type.name}'`);
const f = shape.fields.get(key);
if (!f) throw new NotInSubset(node, `'${base.type.name}' has no field '${key}'`);
return this.leafType(node, `${base.type.name}.${key}`, f);
}
if (base.type.k === 'res') {
const shape = this.comps.get(base.type.name);
const f = shape?.fields.get(key);
if (!f) throw new NotInSubset(node, `resource '${base.type.name}' has no field '${key}'`);
return this.leafType(node, `${base.type.name}.${key}`, f);
}
throw new NotInSubset(node, `'${base.name}' has no fields to read`);
}
/**
* The EIR type a stored leaf reads as, or a refusal naming its encoding. An
* integer leaf is `pending`: what is missing is an EIR integer type, without
* which the two sides could not agree — C narrowing an out-of-range double
* is undefined where JS wraps.
*/
private leafType(node: ts.Node, where: string, f: FieldSpec): EirType {
if (f.enc === 'i32' || f.enc === 'u32' || f.enc === 'u8') {
throw new NotInSubset(node,
`'${where}' is stored as ${f.enc}, and this subset has no integer type`
+ ' — reading it as a double could not be reproduced bit-for-bit');
}
return f.type;
}
/**
* `Math.abs(x)` and friends. Only the operations ECMAScript specifies to the
* bit: sin/cos/tan/exp/log/pow are implementation-defined, so a native
* backend and the interpreter would be free to disagree — and a pixel gate
* would go red on trig rather than on a bug.
*/
private mathCall(node: ts.CallExpression): Expr {
const callee = node.expression;
// A module-level pure function, called by name.
if (ts.isIdentifier(callee)) {
const target = this.fns.get(callee.text);
if (!target) {
const why = this.fnFailures.get(callee.text);
throw new NotInSubset(node, why
? `'${callee.text}' cannot be lowered: ${why}`
: `'${callee.text}' is not a function this subset lowers`);
}
if (node.arguments.length !== target.params.length) {
throw new NotInSubset(node,
`${target.name} takes ${target.params.length} argument(s), not ${node.arguments.length}`);
}
const args = node.arguments.map((a) => this.expr(a));
args.forEach((a, i) => {
const want = target.params[i]!.type;
if (a.type.k !== want.k) {
throw new NotInSubset(node.arguments[i]!,
`${target.name} takes a ${want.k} here, not a ${a.type.k}`);
}
});
return { e: 'call', target: { k: 'fn', name: target.name }, args, type: target.ret };
}
const receiver = ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)
? callee.expression.text : null;
if (receiver !== 'Math' && receiver !== 'exact') {
// A method on a RESOURCE is pending: a service is meant to be read
// as memory, so `input.isKeyDown('KeyW')` is a bit at a known offset.
// On anything else it needs an object model, which there is none of.
const recv = ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)
? this.tryLookup(callee.expression.text)
: null;
if (recv && recv.type.k === 'res') {
const method = (callee as ts.PropertyAccessExpression).name.text;
const key = literalKey(node.arguments[0]);
// A service question the shape declares: the host mirrors the
// answer into a bit, so this is a load and a mask. The KEY has
// to be a literal — a bit index is chosen at compile time.
if (node.arguments.length === 1 && key !== null
&& resourceMethodBit(recv.type.name, method, key)) {
return { e: 'svc', base: { p: 'local', id: recv.id }, method, key, type: BOOL };
}
throw new NotInSubset(node, resourceMethodBit(recv.type.name, method, '') !== null
? `${recv.name}.${method}(…) needs a literal key the shape declares`
: `${recv.name}.${method}(…) is a resource method`
+ ' — the contract wants it read as memory, and nothing lowers it yet');
}
throw new NotInSubset(node, 'CallExpression is not an expression this subset lowers', 'permanent');
}
const fn = (callee as ts.PropertyAccessExpression).name.text as MathFn;
const arity = (MATH_FNS as Record<string, number | undefined>)[fn];
const specified = EXACT_FNS.includes(fn);
// The two namespaces divide by who specifies the answer, and the message
// has to say so: refusing `Math.sin` without naming `exact.sin` reads as
// "trigonometry cannot be compiled", which is no longer true.
if (receiver === 'Math' && specified) {
throw new NotInSubset(node,
`Math.${fn} is implementation-defined, so a compiled build may disagree with the `
+ `interpreter — call exact.${fn} instead, which the engine specifies`);
}
if (receiver === 'exact' && !specified) {
throw new NotInSubset(node, `exact.${fn} is not one the engine specifies`
+ (arity === undefined ? '' : ` — Math.${fn} is exact already`));
}
if (arity === undefined) {
throw new NotInSubset(node,
`Math.${fn} is not exactly specified by ECMAScript, so a compiled build would be free to disagree with the interpreter`,
'permanent');
}
if (node.arguments.length !== arity) {
throw new NotInSubset(node, `Math.${fn} takes ${arity} argument(s), not ${node.arguments.length}`);
}
const args = node.arguments.map((a) => this.expr(a));
for (const a of args) {
if (a.type.k !== 'f64') throw new NotInSubset(node, `Math.${fn} takes numbers, not a ${a.type.k}`);
}
return { e: 'call', target: { k: 'math', fn }, args, type: F64 };
}
/** A read of a module-level constant becomes the value, not a load. */
private foldConst(node: ts.Expression): Expr | null {
const path: string[] = [];
let cur: ts.Expression = node;
while (ts.isPropertyAccessExpression(cur)) {
path.unshift(cur.name.text);
cur = cur.expression;
}
if (!ts.isIdentifier(cur)) return null;
// A local of the same name shadows the module constant, as it does in TS.
if (this.scopes.some((sc) => sc.has(cur.text))) return null;
// `Math.PI` is a value the spec pins exactly, so it folds like any other
// literal — the same double on both sides, unlike `Math.sin`.
if (cur.text === 'Math' && path.length === 1 && MATH_CONSTS.includes(path[0]!)) {
return { e: 'const', value: (Math as unknown as Record<string, number>)[path[0]!]!, type: F64 };
}
const v = this.constAt(cur.text, path);
if (v === null || typeof v === 'object') return null;
return typeof v === 'boolean'
? { e: 'const', value: v, type: BOOL }
: { e: 'const', value: v, type: F64 };
}
private expr(node: ts.Expression): Expr {
if (ts.isParenthesizedExpression(node)) return this.expr(node.expression);
if (ts.isNumericLiteral(node)) return { e: 'const', value: Number(node.text), type: F64 };
if (node.kind === ts.SyntaxKind.TrueKeyword) return { e: 'const', value: true, type: BOOL };
if (node.kind === ts.SyntaxKind.FalseKeyword) return { e: 'const', value: false, type: BOOL };
if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
const v = this.expr(node.operand);
return { e: 'neg', v, type: v.type };
}
if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
return { e: 'not', v: this.expr(node.operand), type: BOOL };
}
if (ts.isBinaryExpression(node)) {
const logic = LOGIC_OPS.get(node.operatorToken.kind);
if (logic) {
return { e: 'logic', op: logic, l: this.expr(node.left), r: this.expr(node.right), type: BOOL };
}
const op = BIN_OPS.get(node.operatorToken.kind);
if (!op) throw new NotInSubset(node, `operator '${tokenText(node.operatorToken.kind)}' is not in this subset`);
const l = this.expr(node.left);
const r = this.expr(node.right);
const type = op === '<' || op === '<=' || op === '>' || op === '>=' || op === '==' || op === '!='
? BOOL : F64;
return { e: 'bin', op, l, r, type };
}
if (ts.isConditionalExpression(node)) {
const cond = this.expr(node.condition);
if (cond.type.k !== 'bool') throw new NotInSubset(node.condition, 'a ternary condition must be a boolean');
const then = this.expr(node.whenTrue);
const otherwise = this.expr(node.whenFalse);
if (then.type.k !== otherwise.type.k) {
throw new NotInSubset(node, 'the two arms of a ternary must have the same type');
}
return { e: 'select', cond, then, otherwise, type: then.type };
}
if (ts.isCallExpression(node)) return this.mathCall(node);
if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
const folded = this.foldConst(node);
if (folded) return folded;
return { e: 'read', place: this.place(node), type: this.placeType(node) };
}
// String, array, object, new, await: each needs a heap, and the contract
// has no allocation.
throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not an expression this subset lowers`, 'permanent');
}
}
/**
* `defineComponent('Mover', { speed: 100 })` or `defineTag('Player')` -> a
* shape, or null when a default is not a literal scalar. A TAG is a shape with
* no fields, which is a thing a query can filter on and nothing can read.
*/
function componentShape(call: ts.CallExpression, tag: boolean): CompShape | null {
const [nameArg, defaults] = call.arguments;
if (!nameArg || !ts.isStringLiteral(nameArg)) return null;
if (tag) return { name: nameArg.text, storage: 'host', fields: new Map() };
if (!defaults || !ts.isObjectLiteralExpression(defaults)) return null;
const fields = new Map<string, FieldSpec>();
for (const prop of defaults.properties) {
if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return null;
// `-50` parses as a prefix expression, not a numeric literal. A default
// of a negative number is ordinary, and refusing it took FixtureClamp
// out of the corpus for no reason anyone would guess from the message.
const init = ts.isPrefixUnaryExpression(prop.initializer)
&& prop.initializer.operator === ts.SyntaxKind.MinusToken
? prop.initializer.operand
: prop.initializer;
if (ts.isNumericLiteral(init)) fields.set(prop.name.text, { type: F64, enc: HOST_ENC, offset: null });
else if (init.kind === ts.SyntaxKind.TrueKeyword || init.kind === ts.SyntaxKind.FalseKeyword) {
fields.set(prop.name.text, { type: BOOL, enc: HOST_ENC, offset: null });
} else return null;
}
// defineComponent lands in ScriptStorage — a Map of JS objects — so its
// numbers are f64, unlike an engine component's f32 pool.
return { name: nameArg.text, storage: 'host', fields };
}
/**
* The second argument's leaves, dotted, in declaration order — the same walk
* `eventFieldsOf` makes at run time. Null where it is absent or is not a literal
* of scalars, which is the only shape both sides can agree about.
*/
function declaredPayload(call: ts.CallExpression): string[] | null {
const literal = call.arguments[1];
if (!literal || !ts.isObjectLiteralExpression(literal)) return null;
const out: string[] = [];
const walk = (node: ts.ObjectLiteralExpression, prefix: string): boolean => {
for (const prop of node.properties) {
if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return false;
const path = prefix ? `${prefix}.${prop.name.text}` : prop.name.text;
if (ts.isObjectLiteralExpression(prop.initializer)) {
if (!walk(prop.initializer, path)) return false;
} else out.push(path);
}
return true;
};
return walk(literal, '') ? out : null;
}
/**
* `defineEvent<{ target: Entity; amount: number }>('DamageDealt')` -> a shape.
*
* A payload's fields live only in the TYPE argument, read as syntax rather than
* asked of the checker. A named type resolves against the program's own
* interfaces; nesting flattens to dotted paths, as a component's does.
*/
function eventShape(
call: ts.CallExpression, interfaces: ReadonlyMap<string, ts.InterfaceDeclaration>,
): CompShape | null {
const nameArg = call.arguments[0];
const arg = call.typeArguments?.[0];
if (!nameArg || !ts.isStringLiteral(nameArg) || !arg) return null;
const fields = new Map<string, FieldSpec>();
const members = (t: ts.TypeNode): readonly ts.TypeElement[] | null => {
if (ts.isTypeLiteralNode(t)) return t.members;
if (ts.isTypeReferenceNode(t) && ts.isIdentifier(t.typeName)) {
return interfaces.get(t.typeName.text)?.members ?? null;
}
return null;
};
const walk = (t: ts.TypeNode, prefix: string): boolean => {
const ms = members(t);
if (!ms) return false;
for (const m of ms) {
if (!ts.isPropertySignature(m) || !ts.isIdentifier(m.name) || !m.type) return false;
const path = prefix ? `${prefix}.${m.name.text}` : m.name.text;
const leaf = eventLeaf(m.type);
if (leaf) { fields.set(path, leaf); continue; }
if (!walk(m.type, path)) return false;
}
return true;
};
if (!walk(arg, '') || fields.size === 0) return null;
// A host record like a `defineComponent` shape: f64 per leaf, laid out by
// the ABI rather than by any C++ struct.
return { name: nameArg.text, storage: 'host', fields };
}
/** A payload leaf: the three types an event field may be. */
function eventLeaf(t: ts.TypeNode): FieldSpec | null {
if (t.kind === ts.SyntaxKind.NumberKeyword) return { type: F64, enc: HOST_ENC, offset: null };
if (t.kind === ts.SyntaxKind.BooleanKeyword) return { type: BOOL, enc: HOST_ENC, offset: null };
// `Entity` is a branded number, and the ABI carries it as one.
if (ts.isTypeReferenceNode(t) && ts.isIdentifier(t.typeName) && t.typeName.text === 'Entity') {
return { type: ENTITY, enc: HOST_ENC, offset: null };
}
return null;
}
/**
* `defineResource<T>({ value: 0 }, 'Score')` -> a shape. The same rule a
* component's defaults meet, for the same reason: every field is one f64, and
* anything else has no fixed width.
*/
function resourceShapeOf(call: ts.CallExpression, name: string): CompShape | null {
const defaults = call.arguments[0];
if (!defaults || !ts.isObjectLiteralExpression(defaults)) return null;
const fields = new Map<string, FieldSpec>();
for (const prop of defaults.properties) {
if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return null;
const init = ts.isPrefixUnaryExpression(prop.initializer)
&& prop.initializer.operator === ts.SyntaxKind.MinusToken
? prop.initializer.operand : prop.initializer;
if (ts.isNumericLiteral(init)) fields.set(prop.name.text, { type: F64, enc: HOST_ENC, offset: null });
else if (init.kind === ts.SyntaxKind.TrueKeyword || init.kind === ts.SyntaxKind.FalseKeyword) {
fields.set(prop.name.text, { type: BOOL, enc: HOST_ENC, offset: null });
} else return null;
}
return fields.size === 0 ? null : { name, storage: 'host', fields };
}
/** Two declarations of one name are the same component only if every field matches. */
function sameShape(a: CompShape, b: CompShape): boolean {
if (a.fields.size !== b.fields.size) return false;
for (const [k, f] of a.fields) {
const other = b.fields.get(k);
if (other?.type.k !== f.type.k || other.enc !== f.enc || other.offset !== f.offset) return false;
}
return true;
}
function normalizePath(p: string): string {
return p.split(sep).join('/').toLowerCase();
}
/**
* The source file is passed in rather than taken from the node: `getSourceFile()`
* walks parent pointers, which only exist once the program has bound — a side
* effect of calling getTypeChecker(), and not something to depend on.
*/
function lineOf(sf: ts.SourceFile, node: ts.Node): number {
return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
}
/**
* Lower every `defineSystem` in `files`. Builtin component and resource shapes
* come in from the caller — EHT is their authority, and inventing a second copy
* here is exactly the drift the ABI hash exists to prevent.
*
* `files` is ONE PROGRAM — one game project, the unit pipeline/ cooks. A
* component's identity is its declared name WITHIN that program; declaring one
* name twice with different fields is a diagnostic, never an overwrite.
*/
export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<string, CompShape>): LowerResult {
const program = ts.createProgram([...files], {
target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext,
strict: true, noEmit: true, skipLibCheck: true, allowJs: false,
});
const comps = new Map<string, CompShape>(builtins);
// A component's declared name and the const it is bound to are two different
// things; move.ts happens to use one word for both, which is why this was
// missing until a fixture used two.
const bindings = new Map<string, string>();
/** Event payloads, by declared name — a second namespace from components. */
const events = new Map<string, CompShape>();
const eventBindings = new Map<string, string>();
/** Events declared with no payload value, which compiled code may not use. */
const unpayloaded = new Set<string>();
/** Resources the PROJECT declared, whose layout travels in the manifest. */
const userResources = new Set<string>();
const consts = new Map<string, ConstValue>();
const fns = new Map<string, EirFn>();
// Why a function could not be lowered, reported at the CALL SITE rather than
// where it was declared: a helper nothing calls has blocked nothing, and a
// diagnostic for it is noise that buries the list of real blockers.
const fnFailures = new Map<string, string>();
const systems: EirSystem[] = [];
const diagnostics: Diagnostic[] = [];
const seen: string[] = [];
const systemBindings = new Map<string, string>();
const required: string[] = [];
// ts normalises fileName to forward slashes; a caller on Windows will not
// have. Comparing them raw lowers nothing and reports no error at all.
const wanted = new Set(files.map(normalizePath));
const sources = program.getSourceFiles()
.filter((sf) => wanted.has(normalizePath(sf.fileName)) && !sf.isDeclarationFile);
// Both scans carry the enclosing `const` name down instead of reading
// node.parent: parent pointers exist only once the program has bound, which
// is a side effect of getTypeChecker() and not a thing to depend on.
/** `marked` is the `@compiled` tag from the enclosing statement, carried down
* to the `defineSystem` call the same way `binding` is. */
type Visit = (node: ts.Node, binding: string | null, marked: boolean) => void;
const walkTop = (sf: ts.SourceFile, visit: Visit): void => {
const go = (node: ts.Node, binding: string | null, marked: boolean): void => {
const here = marked || marksCompiled(node);
visit(node, binding, here);
if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
go(node.initializer, node.name.text, here);
return;
}
ts.forEachChild(node, (c) => go(c, null, here));
};
ts.forEachChild(sf, (c) => go(c, null, false));
};
// Constants and components first: a system in one file names both from another.
for (const sf of sources) {
walkTop(sf, (node) => {
// The declaration's own name, not the binding walkTop passes DOWN to
// an initializer: at the declaration node itself that is still null.
if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer) return;
const v = constValue(node.initializer);
if (v !== null) consts.set(node.name.text, v);
});
}
// Interfaces first: an event's payload may name one declared in another file.
const interfaces = new Map<string, ts.InterfaceDeclaration>();
for (const sf of sources) {
ts.forEachChild(sf, (node) => {
if (ts.isInterfaceDeclaration(node)) interfaces.set(node.name.text, node);
});
}
for (const sf of sources) {
walkTop(sf, (node, binding) => {
if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;
if (node.expression.text === 'defineResource') {
// A project's own resource is a shape like any other: its
// DEFAULTS are a literal, so nothing here has to be taught
// about it the way an engine service does.
const named = node.arguments[1];
if (!named || !ts.isStringLiteral(named)) return;
const shape = resourceShapeOf(node, named.text);
if (!shape) {
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node), kind: 'permanent', severity: 'note',
message: `defineResource('${named.text}') has a default that is not a literal `
+ 'number or boolean',
});
return;
}
comps.set(shape.name, shape);
userResources.add(shape.name);
if (binding) bindings.set(binding, shape.name);
return;
}
if (node.expression.text === 'defineEvent') {
const shape = eventShape(node, interfaces);
if (!shape) {
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node), kind: 'pending', severity: 'note',
message: 'defineEvent needs a payload whose fields are all number, boolean or Entity',
});
return;
}
const clash = comps.get(shape.name);
if (clash && !sameShape(clash, shape)) {
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node), kind: 'permanent', severity: 'note',
message: `'${shape.name}' is declared both as an event and as something else`
+ ' — one program cannot hold two',
});
return;
}
// The payload as a VALUE, held against it as a type: the layout
// comes from the type and the runtime can read only the value,
// so a disagreement is two halves over different fields.
const declared = declaredPayload(node);
if (declared === null) unpayloaded.add(shape.name);
else if (declared.join(',') !== [...shape.fields.keys()].join(',')) {
unpayloaded.add(shape.name);
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node), kind: 'permanent', severity: 'note',
message: `'${shape.name}' declares the payload [${declared.join(', ')}] and its`
+ ` type says [${[...shape.fields.keys()].join(', ')}] — one of the two moved`,
});
}
events.set(shape.name, shape);
// ONE shape table downstream: a payload's fields are read the
// same way a component's are, so every later pass finds them
// without asking which kind of thing this name is.
comps.set(shape.name, shape);
if (binding) eventBindings.set(binding, shape.name);
return;
}
const tag = node.expression.text === 'defineTag';
if (!tag && node.expression.text !== 'defineComponent') return;
const shape = componentShape(node, tag);
if (!shape) {
// Which is nearly always a FIELD, not the call: a default that
// is an object, an array or a computed value has no fixed width,
// and the pool that would hold the rows admits the same set.
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node),
kind: 'permanent', severity: 'note',
message: `defineComponent('${ts.isStringLiteral(node.arguments[0] ?? node) ? (node.arguments[0] as ts.StringLiteral).text : '…'}') `
+ 'has a default that is not a literal number or boolean',
});
return;
}
const existing = comps.get(shape.name);
if (existing && !sameShape(existing, shape)) {
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node), kind: 'permanent', severity: 'note',
message: `component '${shape.name}' is already declared with a different shape`
+ ` — one program cannot hold two`,
});
return;
}
comps.set(shape.name, shape);
if (binding) bindings.set(binding, shape.name);
});
}
// Functions before systems, and in dependency order by repeated passes: a
// helper may call a helper declared later in the file.
for (let pass = 0; pass < 2; pass++) {
for (const sf of sources) {
walkTop(sf, (node, binding) => {
let name: string | null = null;
let params: readonly ts.ParameterDeclaration[] | null = null;
let body: ts.ConciseBody | null = null;
if (ts.isFunctionDeclaration(node) && node.name && node.body) {
name = node.name.text; params = node.parameters; body = node.body;
} else if (binding && ts.isArrowFunction(node)) {
name = binding; params = node.parameters; body = node.body;
}
if (!name || !params || !body || fns.has(name)) return;
try {
fns.set(name, new SystemLowerer(comps, bindings, consts, fns, fnFailures, events, eventBindings, unpayloaded)
.lowerFn(name, params, body));
} catch (e) {
if (!(e instanceof NotInSubset)) throw e;
// Recorded on the last pass only: an earlier failure may just
// be a helper whose own callee is not lowered yet.
if (pass === 1) fnFailures.set(name, e.message);
}
});
}
}
for (const sf of sources) {
walkTop(sf, (node, binding, marked) => {
if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;
if (node.expression.text !== 'defineSystem') return;
const name = systemName(node, binding);
seen.push(name);
if (binding) systemBindings.set(binding, name);
if (marked) required.push(name);
try {
const [params, fn] = node.arguments;
if (!params || !fn || !ts.isArrowFunction(fn)) {
throw new NotInSubset(node, 'defineSystem takes a parameter array and an arrow function');
}
systems.push(new SystemLowerer(comps, bindings, consts, fns, fnFailures, events,
eventBindings, unpayloaded).lower(name, params, fn));
} catch (e) {
if (!(e instanceof NotInSubset)) throw e;
diagnostics.push({
file: sf.fileName, line: lineOf(sf, e.node), message: e.message, kind: e.kind,
// The marker does not change WHY a system was refused, only
// whether anybody has to act on it.
severity: marked ? 'error' : 'note',
system: name,
});
}
});
}
return { module: { systems, comps, fns, events, userResources }, diagnostics, seen, systemBindings, required };
}
/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */
function systemName(call: ts.CallExpression, binding: string | null): string {
const opts = call.arguments[2];
if (opts && ts.isObjectLiteralExpression(opts)) {
for (const p of opts.properties) {
if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'name'
&& ts.isStringLiteral(p.initializer)) {
return p.initializer.text;
}
}
}
return binding ?? '<anonymous>';
}