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
feat(compiler): a shipped system is lowered to EIR and moves a world like node
yhh96cccdfe0862
diff --git a/compiler/package.json b/compiler/package.jsonnew file mode 100644index 000000000..e12b86ded--- /dev/null+++ b/compiler/package.json@@ -0,0 +1,17 @@+{+ "name": "@estella/compiler",+ "version": "0.0.0",+ "private": true,+ "type": "module",+ "description": "Estella AOT — TypeScript to Estella IR (docs/REARCH_AOT.md)",+ "main": "src/index.ts",+ "scripts": {+ "test": "vitest run",+ "typecheck": "tsc --noEmit -p tsconfig.json"+ },+ "devDependencies": {+ "@types/node": "^22.0.0",+ "typescript": "^5.6.0",+ "vitest": "^2.1.9"+ }+}diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.tsnew file mode 100644index 000000000..ad5ef6210--- /dev/null+++ b/compiler/src/builtins.ts@@ -0,0 +1,67 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file builtins.ts+ * @brief Engine component shapes, from EHT's table rather than a second copy.+ *+ * @details PTR_LAYOUTS is generated from the C++ structs and is what the SDK's+ * accessors and the ABI hash already agree on. The compiler consumes it+ * for the same reason: a component's fields must have exactly one+ * author (docs/REARCH_AOT.md §1.2).+ *+ * Resources have no such table yet — `Time` is spelled out below and+ * marked, because a shape with no generator is exactly the drift this+ * file exists to avoid.+ */+import { PTR_LAYOUTS } from '../../sdk/src/wasm/ptrLayouts.generated';+import { BOOL, F64, type CompShape, type EirType } from './eir';++/** Leaf member names per composite field, in memory order. */+const MEMBERS: Record<string, readonly string[]> = {+ vec2: ['x', 'y'],+ vec3: ['x', 'y', 'z'],+ vec4: ['x', 'y', 'z', 'w'],+ quat: ['x', 'y', 'z', 'w'],+ color: ['r', 'g', 'b', 'a'],+};++function leafType(t: string): EirType {+ return t === 'bool' ? BOOL : F64;+}++/**+ * Every engine component EHT emits a layout for, flattened to leaf paths.+ * `Transform` becomes `position.x`, `position.y`, … so a place's path is the+ * key, which is what lets a later pass fold it to a constant offset.+ */+export function builtinShapes(): Map<string, CompShape> {+ const out = new Map<string, CompShape>();+ for (const [name, layout] of Object.entries(PTR_LAYOUTS)) {+ const fields = new Map<string, EirType>();+ for (const f of layout.fields) {+ const members = MEMBERS[f.type];+ if (members) {+ for (const m of members) fields.set(`${f.name}.${m}`, F64);+ } else if (f.type === 'struct') {+ for (const m of f.members ?? []) fields.set(`${f.name}.${m.name}`, leafType(m.type));+ } else {+ fields.set(f.name, leafType(f.type));+ }+ }+ out.set(name, { name, fields });+ }+ out.set('Time', TIME);+ return out;+}++// NOT generated. Resources have no EHT table, so this is a hand-written shape and+// will drift the moment Time gains a field. Generating it is owed before the+// compiler reads any resource beyond this one.+const TIME: CompShape = {+ name: 'Time',+ fields: new Map<string, EirType>([+ ['delta', F64], ['elapsed', F64], ['frameCount', F64],+ ['fixedDelta', F64], ['fixedAlpha', F64], ['fixedTick', F64],+ ['scale', F64], ['unscaledDelta', F64],+ ]),+};diff --git a/compiler/src/eir.ts b/compiler/src/eir.tsnew file mode 100644index 000000000..afb6614b5--- /dev/null+++ b/compiler/src/eir.ts@@ -0,0 +1,154 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file eir.ts+ * @brief Estella IR, high level — typed, and ECS-aware (docs/REARCH_AOT.md §4).+ *+ * @details The reason this layer exists rather than lowering the TS AST straight+ * to LLVM: by LLVM IR a query is an opaque call, and the optimisations+ * that pay — copy-in/copy-out elimination, archetype specialisation,+ * query fusion, change-detection sinking — need to see that a system+ * walks rows of components. Once that is gone it cannot be recovered.+ *+ * So `RowLoop` is a first-class statement here and `CompField` a+ * first-class place, instead of both being calls.+ *+ * Statement tree, not a CFG. The doc puts SSA and explicit memory at+ * EIR-low; making this one a CFG too would buy nothing a Stage 1+ * interpreter can use, and the split is where RC insertion and+ * bounds-check elimination will live.+ */++/** Every value in EIR carries one of these; there is no `any` to fall back to. */+export type EirType =+ | { readonly k: 'f64' }+ | { readonly k: 'bool' }+ | { readonly k: 'entity' }+ /** A component row — its fields come from the component's declared shape. */+ | { readonly k: 'comp'; readonly name: string }+ /** A resource, addressed by field like a component. */+ | { readonly k: 'res'; readonly name: string }+ | { readonly k: 'query'; readonly args: readonly QueryArg[] };++export const F64: EirType = { k: 'f64' };+export const BOOL: EirType = { k: 'bool' };+export const ENTITY: EirType = { k: 'entity' };++/** One component a query asks for, and whether the system may write it. */+export interface QueryArg {+ readonly comp: string;+ readonly mut: boolean;+}++export type BinOp = '+' | '-' | '*' | '/' | '%' | '<' | '<=' | '>' | '>=' | '==' | '!=';++/**+ * A place a value can be read from or written to. `Field` addresses a component+ * or resource by a path of names — `position.x` — which is what lets a later+ * pass turn it into one load at a constant offset.+ */+export type Place =+ | { readonly p: 'local'; readonly id: number }+ | { readonly p: 'field'; readonly base: Place; readonly path: readonly string[] };++export type Expr =+ | { readonly e: 'const'; readonly value: number | boolean; readonly type: EirType }+ | { readonly e: 'read'; readonly place: Place; readonly type: EirType }+ | { readonly e: 'bin'; readonly op: BinOp; readonly l: Expr; readonly r: Expr; readonly type: EirType }+ | { readonly e: 'neg'; readonly v: Expr; readonly type: EirType };++export type Stmt =+ /**+ * Walk every row the query matches, binding the entity and one local per+ * component. The op that must survive to EIR-low as a strided walk.+ */+ | {+ readonly s: 'rowLoop';+ readonly query: Place;+ readonly entity: number | null;+ readonly binds: readonly number[];+ readonly body: readonly Stmt[];+ }+ | { readonly s: 'assign'; readonly target: Place; readonly value: Expr }+ | { readonly s: 'let'; readonly id: number; readonly value: Expr };++/** A local's name and type; the name is for diagnostics and printing only. */+export interface Local {+ readonly id: number;+ readonly name: string;+ readonly type: EirType;+}++export interface EirSystem {+ readonly name: string;+ /** Locals bound to the system's declared parameters, in declaration order. */+ readonly params: readonly Local[];+ readonly locals: readonly Local[];+ readonly body: readonly Stmt[];+}++/** A component's field shape, flattened to leaf paths of one scalar each. */+export interface CompShape {+ readonly name: string;+ /** `position.x` -> f64. Order is the declaration order EHT would give. */+ readonly fields: ReadonlyMap<string, EirType>;+}++export interface EirModule {+ readonly systems: readonly EirSystem[];+ readonly comps: ReadonlyMap<string, CompShape>;+}++// =============================================================================+// printing — an EIR dump is the first thing anyone debugging this will read+// =============================================================================++export function typeName(t: EirType): string {+ switch (t.k) {+ case 'comp': return `comp<${t.name}>`;+ case 'res': return `res<${t.name}>`;+ case 'query': return `query<${t.args.map((a) => (a.mut ? `mut ${a.comp}` : a.comp)).join(', ')}>`;+ default: return t.k;+ }+}++function placeName(p: Place, locals: ReadonlyMap<number, Local>): string {+ if (p.p === 'local') return locals.get(p.id)?.name ?? `%${p.id}`;+ return `${placeName(p.base, locals)}.${p.path.join('.')}`;+}++function exprText(e: Expr, locals: ReadonlyMap<number, Local>): string {+ switch (e.e) {+ case 'const': return String(e.value);+ case 'read': return placeName(e.place, locals);+ case 'bin': return `(${exprText(e.l, locals)} ${e.op} ${exprText(e.r, locals)})`;+ case 'neg': return `-${exprText(e.v, locals)}`;+ }+}++function stmtText(s: Stmt, locals: ReadonlyMap<number, Local>, indent: string): string[] {+ switch (s.s) {+ case 'rowLoop': {+ const names = s.binds.map((b) => locals.get(b)?.name ?? `%${b}`);+ const ent = s.entity === null ? '_' : (locals.get(s.entity)?.name ?? `%${s.entity}`);+ const head = `${indent}rowLoop ${placeName(s.query, locals)} -> (${ent}, ${names.join(', ')}) {`;+ const body = s.body.flatMap((b) => stmtText(b, locals, `${indent} `));+ return [head, ...body, `${indent}}`];+ }+ case 'assign':+ return [`${indent}${placeName(s.target, locals)} = ${exprText(s.value, locals)}`];+ case 'let':+ return [`${indent}let ${locals.get(s.id)?.name ?? `%${s.id}`} = ${exprText(s.value, locals)}`];+ }+}++export function printSystem(sys: EirSystem): string {+ const byId = new Map<number, Local>();+ for (const l of [...sys.params, ...sys.locals]) byId.set(l.id, l);+ const params = sys.params.map((p) => `${p.name}: ${typeName(p.type)}`).join(', ');+ return [+ `system ${sys.name}(${params}) {`,+ ...sys.body.flatMap((s) => stmtText(s, byId, ' ')),+ '}',+ ].join('\n');+}diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.tsnew file mode 100644index 000000000..d84a26bf9--- /dev/null+++ b/compiler/src/frontend.ts@@ -0,0 +1,407 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file frontend.ts+ * @brief TypeScript AST -> EIR-high (docs/REARCH_AOT.md §4.1, §3.3).+ *+ * @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 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 — §3.2's no-cliff rule, which is what+ * lets this ship before it is finished.+ */+import { sep } from 'node:path';+import ts from 'typescript';+import {+ BOOL, ENTITY, F64,+ type CompShape, type EirModule, type EirSystem, type EirType,+ type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp,+} from './eir';++export interface Diagnostic {+ readonly file: string;+ readonly line: number;+ readonly message: string;+ /** 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[];+}++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);++/** Thrown internally to abandon one system; never escapes lowerProgram. */+class NotInSubset extends Error {+ constructor(readonly node: ts.Node, message: string) { super(message); }+}++class SystemLowerer {+ private readonly locals: Local[] = [];+ private next = 0;+ private readonly scope = new Map<string, Local>();++ 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>,+ ) {}++ 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.scope.set(name, l);+ return l;+ }++ private lookup(node: ts.Node, name: string): Local {+ const l = this.scope.get(name);+ if (!l) throw new NotInSubset(node, `'${name}' is not a value this system declared`);+ return l;+ }++ /** `[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') {+ const arg = el.arguments[0];+ if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, 'Res(...) needs a named resource');+ return { k: 'res', name: this.compName(arg.text) } as EirType;+ }+ if (kind !== 'Query') throw new NotInSubset(el, `'${kind}' is not a parameter intrinsic`);+ 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)) return [this.assignment(node.expression)];+ if (ts.isBlock(node)) return node.statements.flatMap((s) => this.stmt(s));+ throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not a statement this subset lowers`);+ }++ /** `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;+ 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]');+ }+ 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.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);+ });++ const body = 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 };+ }++ 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);+ 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, `'${node.operatorToken.getText()}' is not an assignment this subset lowers`);+ }+ return { s: 'assign', target, value: this.expr(node.right) };+ }++ /** 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)) 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');+ 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 t = shape.fields.get(key);+ if (!t) throw new NotInSubset(node, `'${base.type.name}' has no field '${key}'`);+ return t;+ }+ if (base.type.k === 'res') {+ const shape = this.comps.get(base.type.name);+ const t = shape?.fields.get(key);+ if (!t) throw new NotInSubset(node, `resource '${base.type.name}' has no field '${key}'`);+ return t;+ }+ throw new NotInSubset(node, `'${base.name}' has no fields to read`);+ }++ 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.isBinaryExpression(node)) {+ const op = BIN_OPS.get(node.operatorToken.kind);+ if (!op) throw new NotInSubset(node, `operator '${node.operatorToken.getText()}' 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.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {+ return { e: 'read', place: this.place(node), type: this.placeType(node) };+ }+ throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not an expression this subset lowers`);+ }+}++/** `defineComponent('Mover', { speed: 100 })` -> a shape, or null if not literal. */+function componentShape(call: ts.CallExpression): CompShape | null {+ const [nameArg, defaults] = call.arguments;+ if (!nameArg || !ts.isStringLiteral(nameArg)) return null;+ if (!defaults || !ts.isObjectLiteralExpression(defaults)) return null;+ const fields = new Map<string, EirType>();+ for (const prop of defaults.properties) {+ if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return null;+ const init = prop.initializer;+ if (ts.isNumericLiteral(init)) fields.set(prop.name.text, F64);+ else if (init.kind === ts.SyntaxKind.TrueKeyword || init.kind === ts.SyntaxKind.FalseKeyword) {+ fields.set(prop.name.text, BOOL);+ } else return null;+ }+ return { name: nameArg.text, fields };+}++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.+ */+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>();+ const systems: EirSystem[] = [];+ const diagnostics: Diagnostic[] = [];+ const seen: 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.+ type Visit = (node: ts.Node, binding: string | null) => void;+ const walkTop = (sf: ts.SourceFile, visit: Visit): void => {+ const go = (node: ts.Node, binding: string | null): void => {+ visit(node, binding);+ if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {+ go(node.initializer, node.name.text);+ return;+ }+ ts.forEachChild(node, (c) => go(c, null));+ };+ ts.forEachChild(sf, (c) => go(c, null));+ };++ // Components first: a system in one file names a component declared in another.+ for (const sf of sources) {+ walkTop(sf, (node, binding) => {+ if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;+ if (node.expression.text !== 'defineComponent') return;+ const shape = componentShape(node);+ if (!shape) {+ diagnostics.push({+ file: sf.fileName, line: lineOf(sf, node),+ message: 'defineComponent needs a string literal name and an object literal of literal defaults',+ });+ return;+ }+ comps.set(shape.name, shape);+ if (binding) bindings.set(binding, shape.name);+ });+ }++ for (const sf of sources) {+ walkTop(sf, (node, binding) => {+ if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;+ if (node.expression.text !== 'defineSystem') return;+ const name = systemName(node, binding);+ seen.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).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, system: name,+ });+ }+ });+ }++ return { module: { systems, comps }, diagnostics, seen };+}++/** `{ 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>';+}diff --git a/compiler/src/index.ts b/compiler/src/index.tsnew file mode 100644index 000000000..d7ccd8a52--- /dev/null+++ b/compiler/src/index.ts@@ -0,0 +1,11 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file index.ts+ * @brief Estella AOT compiler — public surface (docs/REARCH_AOT.md Stage 1).+ */+export * from './eir';+export { lowerProgram, type Diagnostic, type LowerResult } from './frontend';+export { verifySystem, type VerifyError } from './verify';+export { runSystem, type EirWorld, type Row } from './interp';+export { builtinShapes } from './builtins';diff --git a/compiler/src/interp.ts b/compiler/src/interp.tsnew file mode 100644index 000000000..c5bb17cf7--- /dev/null+++ b/compiler/src/interp.ts@@ -0,0 +1,138 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file interp.ts+ * @brief A reference interpreter for EIR-high (docs/REARCH_AOT.md §8.1).+ *+ * @details Written before any code generation, for two reasons. It proves the IR+ * means something on its own, and it is the third implementation a+ * differential test needs: when compiled output and node disagree, an+ * oracle that is neither says which one is wrong.+ *+ * Deliberately dumb — a tree walk with no caching. Its job is to be+ * obviously correct, not fast; anything clever here would be a second+ * place for a bug to hide from the backend it exists to check.+ */+import type { EirSystem, Expr, Local, Place, QueryArg, Stmt } from './eir';++/** One component instance, nested exactly as a system reads it. */+export type Row = Record<string, unknown>;++export interface EirWorld {+ /** Entity ids in the order a query walks them. */+ readonly entities: readonly number[];+ /** component name -> entity -> its row. An absent entity simply has none. */+ readonly comps: ReadonlyMap<string, Map<number, Row>>;+ readonly resources: ReadonlyMap<string, Row>;+}++class Frame {+ private readonly slots = new Map<number, unknown>();+ set(id: number, v: unknown): void { this.slots.set(id, v); }+ get(id: number): unknown {+ if (!this.slots.has(id)) throw new Error(`EIR: local %${id} read before it was bound`);+ return this.slots.get(id);+ }+}++function walk(root: unknown, path: readonly string[]): { owner: Record<string, unknown>; key: string } {+ let cur = root as Record<string, unknown>;+ for (let i = 0; i < path.length - 1; i++) {+ const next = cur[path[i]!];+ if (next === null || typeof next !== 'object') {+ throw new Error(`EIR: '${path.slice(0, i + 1).join('.')}' is not a value with fields`);+ }+ cur = next as Record<string, unknown>;+ }+ return { owner: cur, key: path[path.length - 1]! };+}++function readPlace(p: Place, frame: Frame): unknown {+ if (p.p === 'local') return frame.get(p.id);+ const base = readPlace(p.base, frame);+ const { owner, key } = walk(base, p.path);+ return owner[key];+}++function writePlace(p: Place, frame: Frame, value: unknown): void {+ if (p.p === 'local') { frame.set(p.id, value); return; }+ const base = readPlace(p.base, frame);+ const { owner, key } = walk(base, p.path);+ owner[key] = value;+}++function evalExpr(e: Expr, frame: Frame): number | boolean {+ switch (e.e) {+ case 'const': return e.value;+ case 'read': return readPlace(e.place, frame) as number | boolean;+ case 'neg': return -(evalExpr(e.v, frame) as number);+ case 'bin': {+ const l = evalExpr(e.l, frame) as number;+ const r = evalExpr(e.r, frame) as number;+ switch (e.op) {+ case '+': return l + r;+ case '-': return l - r;+ case '*': return l * r;+ case '/': return l / r;+ case '%': return l % r;+ case '<': return l < r;+ case '<=': return l <= r;+ case '>': return l > r;+ case '>=': return l >= r;+ case '==': return l === r;+ case '!=': return l !== r;+ }+ }+ }+}++/** Entities carrying every component the query names, in world order. */+function matching(world: EirWorld, args: readonly QueryArg[]): number[] {+ return world.entities.filter((e) => args.every((a) => world.comps.get(a.comp)?.has(e)));+}++function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {+ for (const s of stmts) {+ switch (s.s) {+ case 'let':+ frame.set(s.id, evalExpr(s.value, frame));+ break;+ case 'assign':+ writePlace(s.target, frame, evalExpr(s.value, frame));+ break;+ case 'rowLoop': {+ const q = readPlace(s.query, frame) as { args: readonly QueryArg[] };+ for (const entity of matching(world, q.args)) {+ if (s.entity !== null) frame.set(s.entity, entity);+ s.binds.forEach((id, i) => {+ frame.set(id, world.comps.get(q.args[i]!.comp)!.get(entity)!);+ });+ exec(s.body, frame, world);+ }+ break;+ }+ }+ }+}++/**+ * Run `sys` against `world`, mutating it in place. Parameters are bound from+ * their declared types: a query becomes its own argument list, a resource its+ * row — the same two things the SDK's runner resolves.+ */+export function runSystem(sys: EirSystem, world: EirWorld): void {+ const frame = new Frame();+ for (const p of sys.params) bindParam(p, frame, world);+ exec(sys.body, frame, world);+}++function bindParam(p: Local, frame: Frame, world: EirWorld): void {+ if (p.type.k === 'query') { frame.set(p.id, { args: p.type.args }); return; }+ if (p.type.k === 'res') {+ const row = world.resources.get(p.type.name);+ if (!row) throw new Error(`EIR: no resource '${p.type.name}' in the world`);+ frame.set(p.id, row);+ return;+ }+ throw new Error(`EIR: '${p.name}' has no parameter binding for ${p.type.k}`);+}diff --git a/compiler/src/verify.ts b/compiler/src/verify.tsnew file mode 100644index 000000000..b8061b138--- /dev/null+++ b/compiler/src/verify.ts@@ -0,0 +1,161 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file verify.ts+ * @brief Re-prove an EIR system's types, without looking at the TypeScript.+ *+ * @details docs/REARCH_AOT.md §4.1 asks for this because tsc's types are not+ * sound — structural typing, method bivariance and `any` leak through+ * generics — so a pass has to prove, on the IR, that every value is the+ * type it claims.+ *+ * It reads only EIR, never the AST. That is the point: re-running the+ * frontend's own reasoning would agree with the frontend's own bugs,+ * and the failure this catches is a frontend that lowered something+ * wrong, not a source file that was outside the subset.+ */+import {+ type CompShape, type EirSystem, type EirType, type Expr, type Local, type Place, type Stmt,+ typeName,+} from './eir';++export interface VerifyError {+ readonly system: string;+ readonly message: string;+}++class Verifier {+ private readonly byId = new Map<number, Local>();+ readonly errors: VerifyError[] = [];++ constructor(+ private readonly sys: EirSystem,+ private readonly comps: ReadonlyMap<string, CompShape>,+ ) {+ for (const l of [...sys.params, ...sys.locals]) {+ if (this.byId.has(l.id)) this.fail(`local %${l.id} ('${l.name}') is declared twice`);+ this.byId.set(l.id, l);+ }+ }++ private fail(message: string): void {+ this.errors.push({ system: this.sys.name, message });+ }++ private local(id: number): Local | null {+ const l = this.byId.get(id);+ if (!l) { this.fail(`local %${id} is used but never declared`); return null; }+ return l;+ }++ /** The type a place reads as, or null when it does not resolve. */+ placeType(p: Place): EirType | null {+ if (p.p === 'local') return this.local(p.id)?.type ?? null;+ const base = this.placeType(p.base);+ if (!base) return null;+ if (base.k !== 'comp' && base.k !== 'res') {+ this.fail(`a ${typeName(base)} has no field '${p.path.join('.')}'`);+ return null;+ }+ const shape = this.comps.get(base.name);+ if (!shape) { this.fail(`no declared shape for '${base.name}'`); return null; }+ const t = shape.fields.get(p.path.join('.'));+ if (!t) { this.fail(`'${base.name}' has no field '${p.path.join('.')}'`); return null; }+ return t;+ }++ exprType(e: Expr): EirType | null {+ switch (e.e) {+ case 'const':+ if ((typeof e.value === 'boolean') !== (e.type.k === 'bool')) {+ this.fail(`constant ${String(e.value)} is declared ${typeName(e.type)}`);+ }+ return e.type;+ case 'read': {+ const t = this.placeType(e.place);+ if (t && t.k !== e.type.k) {+ this.fail(`a read declared ${typeName(e.type)} resolves to ${typeName(t)}`);+ }+ return t;+ }+ case 'neg': {+ const t = this.exprType(e.v);+ if (t && t.k !== 'f64') this.fail(`negation of a ${typeName(t)}`);+ return t;+ }+ case 'bin': {+ const l = this.exprType(e.l);+ const r = this.exprType(e.r);+ for (const t of [l, r]) {+ if (t && t.k !== 'f64') this.fail(`operator '${e.op}' applied to a ${typeName(t)}`);+ }+ return e.type;+ }+ }+ }++ stmt(s: Stmt): void {+ switch (s.s) {+ case 'let': {+ const declared = this.local(s.id)?.type;+ const actual = this.exprType(s.value);+ if (declared && actual && declared.k !== actual.k) {+ this.fail(`'${this.byId.get(s.id)?.name}' is ${typeName(declared)} but is bound to ${typeName(actual)}`);+ }+ break;+ }+ case 'assign': {+ const target = this.placeType(s.target);+ const value = this.exprType(s.value);+ if (target && value && target.k !== value.k) {+ this.fail(`assigning ${typeName(value)} into a ${typeName(target)}`);+ }+ break;+ }+ case 'rowLoop': {+ const q = this.placeType(s.query);+ if (!q) break;+ if (q.k !== 'query') { this.fail(`rowLoop over a ${typeName(q)}`); break; }+ if (q.args.length !== s.binds.length) {+ this.fail(`rowLoop binds ${s.binds.length} components for a query of ${q.args.length}`);+ }+ s.binds.forEach((id, i) => {+ const l = this.local(id);+ const want = q.args[i];+ if (!l || !want) return;+ if (l.type.k !== 'comp' || l.type.name !== want.comp) {+ this.fail(`row binds '${l.name}' as ${typeName(l.type)} for component '${want.comp}'`);+ }+ // A component the query did not ask to write must not be a+ // target — the read-only half of Mut, proved here rather than+ // trusted from the source.+ if (!want.mut && this.writesTo(s.body, id)) {+ this.fail(`'${l.name}' is written but the query asks for '${want.comp}' without Mut`);+ }+ });+ if (s.entity !== null) {+ const l = this.local(s.entity);+ if (l && l.type.k !== 'entity') this.fail(`row entity bound as ${typeName(l.type)}`);+ }+ for (const b of s.body) this.stmt(b);+ break;+ }+ }+ }++ private writesTo(body: readonly Stmt[], id: number): boolean {+ const rootOf = (p: Place): number => (p.p === 'local' ? p.id : rootOf(p.base));+ for (const s of body) {+ if (s.s === 'assign' && rootOf(s.target) === id) return true;+ if (s.s === 'rowLoop' && this.writesTo(s.body, id)) return true;+ }+ return false;+ }+}++/** Every type claim in `sys`, re-proved. An empty array means it holds. */+export function verifySystem(sys: EirSystem, comps: ReadonlyMap<string, CompShape>): VerifyError[] {+ const v = new Verifier(sys, comps);+ for (const s of sys.body) v.stmt(s);+ return v.errors;+}diff --git a/compiler/tests/fixtures/dynamic-component.ts b/compiler/tests/fixtures/dynamic-component.tsnew file mode 100644index 000000000..034d022d0--- /dev/null+++ b/compiler/tests/fixtures/dynamic-component.ts@@ -0,0 +1,13 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file dynamic-component.ts+ * @brief A defineComponent whose shape is not a literal.+ *+ * @details §3.3 makes it an intrinsic, so a shape the compiler cannot read at+ * compile time is a fallback, not a guess.+ */+import { defineComponent } from 'esengine';++const defaults = { hp: 100 };+export const Dynamic = defineComponent('FixtureDynamic', defaults);diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.tsnew file mode 100644index 000000000..2900a980e--- /dev/null+++ b/compiler/tests/fixtures/outside-subset.ts@@ -0,0 +1,58 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file outside-subset.ts+ * @brief Systems that must NOT compile.+ *+ * @details Each names a rule from REARCH_AOT §3; subset.test.ts asserts the+ * diagnostic points at the line and says why.+ */+import { defineComponent, defineSystem, Query, Mut, Res, Time, Transform } from 'esengine';++export const Speed = defineComponent('FixtureSpeed', { value: 100 });++/** A branch: no control flow beyond the row loop is lowered yet. */+export const branching = defineSystem(+ [Query(Mut(Transform), Speed)],+ (query) => {+ for (const [_e, t, s] of query) {+ if (s.value > 0) {+ t.position.x += s.value;+ }+ }+ },+ { name: 'FixtureBranching' },+);++/** A field the component does not declare — a typo, caught at compile time. */+export const typoField = defineSystem(+ [Query(Mut(Transform), Speed)],+ (query) => {+ for (const [_e, t, s] of query) {+ t.position.x += s.valeu;+ }+ },+ { name: 'FixtureTypo' },+);++/** A call: nothing outside the intrinsics is reachable from a compiled system. */+export const calling = defineSystem(+ [Query(Mut(Transform), Speed), Res(Time)],+ (query, time) => {+ for (const [_e, t, s] of query) {+ t.position.x += Math.sin(s.value) * time.delta;+ }+ },+ { name: 'FixtureCalling' },+);++/** Writing a component the query did not ask to write. */+export const writesReadOnly = defineSystem(+ [Query(Transform, Speed)],+ (query) => {+ for (const [_e, t, s] of query) {+ t.position.x += s.value;+ }+ },+ { name: 'FixtureWritesReadOnly' },+);diff --git a/compiler/tests/move-system.test.ts b/compiler/tests/move-system.test.tsnew file mode 100644index 000000000..cbd0916cf--- /dev/null+++ b/compiler/tests/move-system.test.ts@@ -0,0 +1,139 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file move-system.test.ts+ * @brief Stage 1's exit criterion, end to end (docs/REARCH_AOT.md §10).+ *+ * @details Takes a real system out of examples/, lowers it to EIR, and holds+ * the interpreter's result against node's.+ *+ * Both sides read the SAME FILE — the oracle is move.ts imported through a+ * stubbed `esengine`, not a copy re-typed here. A copy would agree with+ * whatever the copy got wrong.+ */+import { describe, it, expect } from 'vitest';+import { resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { lowerProgram } from '../src/frontend';+import { verifySystem } from '../src/verify';+import { runSystem, type EirWorld, type Row } from '../src/interp';+import { builtinShapes } from '../src/builtins';+import { printSystem } from '../src/eir';++import { moveSystem } from '../../examples/ecs-basics/src/systems/move';+import type { StubSystem } from './stubs/esengine';++const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));+const FILES = [+ resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),+ resolve(ROOT, 'examples/ecs-basics/src/components.ts'),+];++const ENTITIES = 64;++/** Two identical worlds from one seed, so a difference can only be the system. */+function makeWorld(): EirWorld {+ let a = 0x2f6e2b1 >>> 0;+ const rand = (): number => {+ a = (a * 1664525 + 1013904223) >>> 0;+ return (a >>> 8) / 16777216;+ };+ const transforms = new Map<number, Row>();+ const movers = new Map<number, Row>();+ const entities: number[] = [];+ for (let e = 1; e <= ENTITIES; e++) {+ entities.push(e);+ transforms.set(e, {+ position: { x: (rand() - 0.5) * 200, y: (rand() - 0.5) * 200, z: 0 },+ rotation: { x: 0, y: 0, z: 0, w: 1 },+ scale: { x: 1, y: 1, z: 1 },+ worldPosition: { x: 0, y: 0, z: 0 },+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },+ worldScale: { x: 1, y: 1, z: 1 },+ });+ // Every third entity has no Mover, so "the query matched the right rows"+ // is part of what the comparison proves.+ if (e % 3 !== 0) {+ movers.set(e, { speed: 20 + rand() * 80, directionX: rand() * 2 - 1, directionY: rand() * 2 - 1 });+ }+ }+ return {+ entities,+ comps: new Map([['Transform', transforms], ['Mover', movers]]),+ resources: new Map<string, Row>([['Time', { delta: 1 / 60, elapsed: 0 }]]),+ };+}++/** Run the real callback, handing it live rows the way a Mut query does. */+function runNative(world: EirWorld): void {+ const sys = moveSystem as unknown as StubSystem;+ const transforms = world.comps.get('Transform')!;+ const movers = world.comps.get('Mover')!;+ const query = {+ *[Symbol.iterator]() {+ for (const e of world.entities) {+ if (transforms.has(e) && movers.has(e)) yield [e, transforms.get(e)!, movers.get(e)!];+ }+ },+ };+ (sys.fn as unknown as (q: unknown, t: unknown) => void)(query, world.resources.get('Time'));+}++describe('Stage 1 — a real example system, end to end', () => {+ const { module, diagnostics, seen } = lowerProgram(FILES, builtinShapes());+ const moveEir = module.systems.find((s) => s.name === 'MoveSystem');++ it('lowers MoveSystem out of examples/ecs-basics', () => {+ expect(seen).toContain('MoveSystem');+ expect(diagnostics.filter((d) => d.system === 'MoveSystem')).toEqual([]);+ expect(moveEir).toBeDefined();+ });++ it('reads back as the loop it came from', () => {+ expect(printSystem(moveEir!)).toMatchInlineSnapshot(`+ "system MoveSystem(query: query<mut Transform, Mover>, time: res<Time>) {+ rowLoop query -> (_entity, transform, mover) {+ transform.position.x = (transform.position.x + ((mover.directionX * mover.speed) * time.delta))+ transform.position.y = (transform.position.y + ((mover.directionY * mover.speed) * time.delta))+ }+ }"+ `);+ });++ it('re-proves its own types without looking at the TypeScript', () => {+ expect(verifySystem(moveEir!, module.comps)).toEqual([]);+ });++ it('picks up Mover from defineComponent as a compile-time declaration', () => {+ expect([...module.comps.get('Mover')!.fields.keys()]).toEqual(['speed', 'directionX', 'directionY']);+ });++ it('moves the world exactly the way node does', () => {+ const byNode = makeWorld();+ const byEir = makeWorld();+ expect(byEir).toEqual(byNode);++ for (let frame = 0; frame < 30; frame++) {+ runNative(byNode);+ runSystem(moveEir!, byEir);+ }++ // Bit-for-bit: both sides are f64 doing the same operations in the same+ // order, so "close enough" would hide a real divergence.+ expect(byEir.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));+ expect(byEir.comps.get('Mover')).toEqual(byNode.comps.get('Mover'));+ });++ it('did something — a system that no-ops would also agree', () => {+ const before = makeWorld();+ const after = makeWorld();+ for (let frame = 0; frame < 30; frame++) runSystem(moveEir!, after);+ expect(after.comps.get('Transform')).not.toEqual(before.comps.get('Transform'));+ // The entities without a Mover must NOT have moved.+ for (const e of after.entities) {+ if (e % 3 === 0) {+ expect(after.comps.get('Transform')!.get(e)).toEqual(before.comps.get('Transform')!.get(e));+ }+ }+ });+});diff --git a/compiler/tests/stubs/esengine.ts b/compiler/tests/stubs/esengine.tsnew file mode 100644index 000000000..c1b9739ae--- /dev/null+++ b/compiler/tests/stubs/esengine.ts@@ -0,0 +1,43 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file esengine.ts+ * @brief Enough of the SDK for an example system file to be imported and run.+ *+ * @details The differential needs both sides reading one source, so the oracle+ * has to be the real move.ts rather than a copy living in a test.+ */+export interface StubSystem {+ readonly name: string;+ readonly params: readonly unknown[];+ readonly fn: (...args: any[]) => void;+}++export const Transform = { _name: 'Transform' };+export const Time = { _name: 'Time' };++export function defineComponent(name: string, defaults: Record<string, unknown>): unknown {+ return { _name: name, defaults };+}+export function defineTag(name: string): unknown {+ return { _name: name, defaults: {} };+}+export function Query(...args: unknown[]): unknown {+ return { kind: 'query', args };+}+export function Mut(comp: unknown): unknown {+ return { kind: 'mut', comp };+}+export function Res(resource: unknown): unknown {+ return { kind: 'res', resource };+}+export function defineSystem(+ params: readonly unknown[],+ fn: (...args: any[]) => void,+ opts?: { name?: string },+): StubSystem {+ return { name: opts?.name ?? '<anonymous>', params, fn };+}+export function addSystemToSchedule(): void { /* the example's main.ts calls this */ }+export function addStartupSystem(): void { /* likewise */ }+export const Schedule = { Update: 'Update' } as const;diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.tsnew file mode 100644index 000000000..52aaddf6d--- /dev/null+++ b/compiler/tests/subset.test.ts@@ -0,0 +1,66 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file subset.test.ts+ * @brief What the subset must REFUSE, and how it says so.+ *+ * @details A checker that accepts everything is not a checker. Each case pins a+ * rule from §3 and asserts the refusal names a line and a reason —+ * §11's "coverage stalls low" is a diagnostics problem first.+ */+import { describe, it, expect } from 'vitest';+import { resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { lowerProgram } from '../src/frontend';+import { verifySystem } from '../src/verify';+import { builtinShapes } from '../src/builtins';++const HERE = resolve(fileURLToPath(new URL('.', import.meta.url)));+const OUTSIDE = resolve(HERE, 'fixtures/outside-subset.ts');+const DYNAMIC = resolve(HERE, 'fixtures/dynamic-component.ts');++const result = lowerProgram([OUTSIDE], builtinShapes());+const diagOf = (system: string) => result.diagnostics.find((d) => d.system === system);+const compiled = (system: string) => result.module.systems.some((s) => s.name === system);++describe('the subset refuses, and says why', () => {+ it('saw every system in the file, compiled or not', () => {+ expect(result.seen).toEqual([+ 'FixtureBranching', 'FixtureTypo', 'FixtureCalling', 'FixtureWritesReadOnly',+ ]);+ });++ it.each([+ ['FixtureBranching', /IfStatement is not a statement/],+ ['FixtureTypo', /has no field 'valeu'/],+ ['FixtureCalling', /CallExpression is not an expression/],+ ])('refuses %s', (name, why) => {+ const d = diagOf(name);+ expect(d, `${name} compiled when it should not have`).toBeDefined();+ expect(d!.message).toMatch(why);+ expect(d!.line).toBeGreaterThan(0);+ expect(d!.file).toContain('outside-subset');+ expect(compiled(name)).toBe(false);+ });++ it('lowers a write to a component the query did not ask to write…', () => {+ // The frontend has no reason to refuse this — it is well-formed TS and a+ // well-formed place. Which is exactly why the verifier must catch it.+ expect(diagOf('FixtureWritesReadOnly')).toBeUndefined();+ expect(compiled('FixtureWritesReadOnly')).toBe(true);+ });++ it('…and the verifier refuses it on the IR alone', () => {+ const sys = result.module.systems.find((s) => s.name === 'FixtureWritesReadOnly')!;+ const errors = verifySystem(sys, result.module.comps);+ expect(errors).toHaveLength(1);+ expect(errors[0]!.message).toMatch(/is written but the query asks for 'Transform' without Mut/);+ });++ it('refuses a defineComponent whose shape is not a literal', () => {+ const dyn = lowerProgram([DYNAMIC], builtinShapes());+ expect(dyn.module.comps.has('FixtureDynamic')).toBe(false);+ expect(dyn.diagnostics).toHaveLength(1);+ expect(dyn.diagnostics[0]!.message).toMatch(/object literal of literal defaults/);+ });+});diff --git a/compiler/tsconfig.json b/compiler/tsconfig.jsonnew file mode 100644index 000000000..70474cfe8--- /dev/null+++ b/compiler/tsconfig.json@@ -0,0 +1,17 @@+{+ "compilerOptions": {+ "target": "ES2022",+ "module": "ESNext",+ "moduleResolution": "bundler",+ "strict": true,+ "noUncheckedIndexedAccess": true,+ "exactOptionalPropertyTypes": true,+ "noEmit": true,+ "skipLibCheck": true,+ "baseUrl": ".",+ "paths": { "esengine": ["./tests/stubs/esengine.ts"] },+ "types": []+ },+ "include": ["src/**/*.ts", "tests/**/*.ts"],+ "exclude": ["tests/fixtures/**"]+}diff --git a/compiler/vitest.config.ts b/compiler/vitest.config.tsnew file mode 100644index 000000000..863ac8f29--- /dev/null+++ b/compiler/vitest.config.ts@@ -0,0 +1,13 @@+import { defineConfig } from 'vitest/config';+import { fileURLToPath } from 'node:url';++export default defineConfig({+ test: { include: ['tests/**/*.test.ts'], environment: 'node' },+ resolve: {+ alias: {+ // So a test can import a real example system, whose own imports the+ // stub answers. Without this the oracle would be a re-typed copy.+ esengine: fileURLToPath(new URL('./tests/stubs/esengine.ts', import.meta.url)),+ },+ },+});diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex f119cc895..d8362928a 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -34,6 +34,18 @@ importers:specifier: ^2.1.9version: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])+ compiler:+ devDependencies:+ '@types/node':+ specifier: ^22.0.0+ version: 22.20.1+ typescript:+ specifier: ^5.6.0+ version: 5.9.3+ vitest:+ specifier: ^2.1.9+ version: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])+desktop:dependencies:'@anthropic-ai/sdk':@@ -1255,6 +1267,9 @@ packages:'@types/[email protected]':resolution: {integrity: sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==}+ '@types/[email protected]':+ resolution: {integrity: sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==}+'@types/[email protected]':resolution: {integrity: sha512-fRa09kZTgu8o71KFcDjUFuc7F+dEbZYZmkI0mg5YBTRs0yMKjYHsq/c0urDKeDb+D5qVgXOdFcuu+DZPKOITwA==}@@ -3474,6 +3489,9 @@ packages:resolution: {integrity: sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==}+ resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}+resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}@@ -4532,6 +4550,10 @@ snapshots:'@types/[email protected]': {}+ '@types/[email protected]':+ dependencies:+ undici-types: 6.21.0+'@types/[email protected]':dependencies:undici-types: 7.18.2@@ -4625,6 +4647,14 @@ snapshots:chai: 5.3.3tinyrainbow: 1.2.0+ '@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected]))':+ dependencies:+ '@vitest/spy': 2.1.9+ estree-walker: 3.0.3+ magic-string: 0.30.21+ optionalDependencies:+'@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected]))':dependencies:'@vitest/spy': 2.1.9@@ -4661,7 +4691,7 @@ snapshots:sirv: 3.0.2tinyglobby: 0.2.15tinyrainbow: 1.2.0- vitest: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])+ vitest: 2.1.9(@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected])'@vitest/[email protected]':dependencies:@@ -7016,6 +7046,8 @@ snapshots:+ [email protected]: {}+@@ -7045,6 +7077,24 @@ snapshots:+ dependencies:+ cac: 6.7.14+ debug: 4.4.3+ es-module-lexer: 1.7.0+ pathe: 1.1.2+ transitivePeerDependencies:+ - '@types/node'+ - less+ - lightningcss+ - sass+ - sass-embedded+ - stylus+ - sugarss+ - supports-color+ - terser+dependencies:cac: 6.7.14@@ -7071,6 +7121,17 @@ snapshots:optionalDependencies:vite-plugin-electron-renderer: 1.0.0+ dependencies:+ esbuild: 0.21.5+ postcss: 8.5.6+ rollup: 4.57.1+ optionalDependencies:+ '@types/node': 22.20.1+ fsevents: 2.3.3+ lightningcss: 1.32.0+ terser: 5.46.0+dependencies:esbuild: 0.21.5@@ -7096,6 +7157,44 @@ snapshots:jiti: 2.7.0terser: 5.46.0+ [email protected](@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected]):+ dependencies:+ '@vitest/expect': 2.1.9+ '@vitest/mocker': 2.1.9([email protected](@types/[email protected])([email protected])([email protected]))+ '@vitest/pretty-format': 2.1.9+ '@vitest/runner': 2.1.9+ '@vitest/snapshot': 2.1.9+ '@vitest/spy': 2.1.9+ '@vitest/utils': 2.1.9+ chai: 5.3.3+ debug: 4.4.3+ expect-type: 1.3.0+ magic-string: 0.30.21+ pathe: 1.1.2+ std-env: 3.10.0+ tinybench: 2.9.0+ tinyexec: 0.3.2+ tinypool: 1.1.1+ tinyrainbow: 1.2.0+ why-is-node-running: 2.3.0+ optionalDependencies:+ '@types/node': 22.20.1+ '@vitest/ui': 2.1.9([email protected])+ happy-dom: 15.11.7+ jsdom: 25.0.1+ transitivePeerDependencies:+ - less+ - lightningcss+ - msw+ - sass+ - sass-embedded+ - stylus+ - sugarss+ - supports-color+ - terser+[email protected](@types/[email protected])(@vitest/[email protected])([email protected])([email protected])([email protected])([email protected]):dependencies:'@vitest/expect': 2.1.9diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex 8912c87d9..bd77f70d9 100644--- a/pnpm-workspace.yaml+++ b/pnpm-workspace.yaml@@ -1,6 +1,7 @@packages:- 'sdk'- 'pipeline'+ - 'compiler'- 'desktop'- 'editor-api'- 'plugins/*'diff --git a/tools/gates.mjs b/tools/gates.mjsindex 422b7a23e..984d6024c 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -77,6 +77,9 @@ export const GATES = [// The engine's own TS suites (pipeline + tooling). They lived in desktop/tests// until the editor split, where a checkout without the editor ran none of them.{ id: 'engine-tests', run: 'pnpm run test' },+ // The AOT compiler carries its own oracle: a real example system lowered to+ // EIR must move a world exactly the way node moves it (docs/REARCH_AOT.md §8.1).+ { id: 'compiler-tests', run: 'pnpm --filter @estella/compiler test' },// The plugins we ship prove the public API only if they are held to it.{ id: 'plugin-boundary', run: 'node tools/check-plugin-boundary.mjs' },// Same shape of rule, other direction: what builds a project may not need the