Skip to content

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.

feat(compiler): the author can write down that a system must compile

yhh0ebe34a1a477
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.ts
index 340e63482..49756b117 100644
--- a/compiler/src/frontend.ts
+++ b/compiler/src/frontend.ts
@@ -39,6 +39,12 @@ export interface Diagnostic {
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;
}
@@ -54,6 +60,49 @@ export interface LowerResult {
* 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 §3.2's fallback 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([
@@ -698,6 +747,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
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.
@@ -708,17 +758,20 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
// 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;
+ /** `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): void => {
- visit(node, binding);
+ 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);
+ go(node.initializer, node.name.text, here);
return;
}
- ts.forEachChild(node, (c) => go(c, null));
+ ts.forEachChild(node, (c) => go(c, null, here));
};
- ts.forEachChild(sf, (c) => go(c, null));
+ ts.forEachChild(sf, (c) => go(c, null, false));
};
// Constants and components first: a system in one file names both from another.
@@ -739,7 +792,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
if (!shape) {
diagnostics.push({
file: sf.fileName, line: lineOf(sf, node),
- kind: 'permanent',
+ kind: 'permanent', severity: 'note',
message: 'defineComponent needs a string literal name and an object literal of literal defaults',
});
return;
@@ -747,7 +800,7 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
const existing = comps.get(shape.name);
if (existing && !sameShape(existing, shape)) {
diagnostics.push({
- file: sf.fileName, line: lineOf(sf, node), kind: 'permanent',
+ 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`,
});
@@ -786,12 +839,13 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
}
for (const sf of sources) {
- walkTop(sf, (node, binding) => {
+ 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)) {
@@ -801,13 +855,17 @@ export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<str
} catch (e) {
if (!(e instanceof NotInSubset)) throw e;
diagnostics.push({
- file: sf.fileName, line: lineOf(sf, e.node), message: e.message, kind: e.kind, system: name,
+ 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 }, diagnostics, seen, systemBindings };
+ return { module: { systems, comps, fns }, diagnostics, seen, systemBindings, required };
}
/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */
diff --git a/compiler/src/index.ts b/compiler/src/index.ts
index ed48fec9e..00964ac58 100644
--- a/compiler/src/index.ts
+++ b/compiler/src/index.ts
@@ -5,7 +5,7 @@
* @brief Estella AOT compiler — public surface (docs/REARCH_AOT.md Stages 1-2).
*/
export * from './eir';
-export { lowerProgram, type Diagnostic, type LowerResult } from './frontend';
+export { brokenPromises, lowerProgram, type Diagnostic, type LowerResult } from './frontend';
export { verifySystem, type VerifyError } from './verify';
export { runSystem, type EirWorld, type Fns, type Row } from './interp';
export { inlineModule, inlineSystem } from './inline';
diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.ts
index 8bdb7bbbc..9ae8adf34 100644
--- a/compiler/tests/coverage.test.ts
+++ b/compiler/tests/coverage.test.ts
@@ -30,7 +30,7 @@ import { describe, it, expect } from 'vitest';
import { readFileSync, readdirSync, statSync } from 'node:fs';
import { join, resolve, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
-import { lowerProgram } from '../src/frontend';
+import { brokenPromises, lowerProgram } from '../src/frontend';
import { verifySystem } from '../src/verify';
import { builtinShapes } from '../src/builtins';
@@ -183,3 +183,28 @@ describe('AOT coverage over examples/', () => {
expect(unverified).toEqual([]);
});
});
+
+/**
+ * The coverage number above measures a corpus nobody promised anything about.
+ * This one measures the promises: a system carrying `@compiled` must compile and
+ * verify, and a refusal against one is an error rather than a quiet fallback.
+ * It is the number that can be 100% and STAY 100%.
+ */
+describe('systems the corpus promises to compile', () => {
+ const promised = results.flatMap((r) => r.required);
+
+ it('finds the marker in the corpus at all', () => {
+ // At zero this whole block asserts nothing, which is the failure a gate
+ // is least able to notice about itself.
+ expect(promised.length).toBeGreaterThan(0);
+ console.log(`@compiled promises: ${promised.length} — ${promised.join(', ')}`);
+ });
+
+ it('keeps every one of them', () => {
+ expect(results.flatMap((r) => brokenPromises(r))).toEqual([]);
+ });
+
+ it('and each also verifies, not merely lowers', () => {
+ expect(promised.filter((n) => !verifiedNames.has(n))).toEqual([]);
+ });
+});
diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.ts
index 5d334b807..ced581587 100644
--- a/compiler/tests/fixtures/outside-subset.ts
+++ b/compiler/tests/fixtures/outside-subset.ts
@@ -91,3 +91,35 @@ export const writesConst = defineSystem(
},
{ name: 'FixtureWritesConst' },
);
+
+/**
+ * The same refusal as `FixtureTrig`, but PROMISED.
+ *
+ * @compiled
+ * Without the marker a system that stops compiling just gets slower and nothing
+ * goes red; with it, the refusal is an error naming this line.
+ */
+export const promised = defineSystem(
+ [Query(Mut(Transform), Speed), Res(Time)],
+ (query, time) => {
+ for (const [_e, t, s] of query) {
+ t.position.x += Math.cos(s.value * time.delta);
+ }
+ },
+ { name: 'FixturePromised' },
+);
+
+/**
+ * Marked, and inside the subset: the promise is kept.
+ *
+ * @compiled
+ */
+export const promiseKept = defineSystem(
+ [Query(Mut(Transform), Speed), Res(Time)],
+ (query, time) => {
+ for (const [_e, t, s] of query) {
+ t.position.x += s.value * time.delta;
+ }
+ },
+ { name: 'FixturePromiseKept' },
+);
diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.ts
index d1142ea32..65332a740 100644
--- a/compiler/tests/subset.test.ts
+++ b/compiler/tests/subset.test.ts
@@ -11,7 +11,7 @@
import { describe, it, expect } from 'vitest';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
-import { lowerProgram } from '../src/frontend';
+import { brokenPromises, lowerProgram } from '../src/frontend';
import { verifySystem } from '../src/verify';
import { builtinShapes } from '../src/builtins';
@@ -28,6 +28,7 @@ describe('the subset refuses, and says why', () => {
expect(result.seen).toEqual([
'FixtureLooping', 'FixtureTypo', 'FixtureTrig', 'FixtureCalling',
'FixtureWritesReadOnly', 'FixtureWritesConst',
+ 'FixturePromised', 'FixturePromiseKept',
]);
});
@@ -67,3 +68,29 @@ describe('the subset refuses, and says why', () => {
expect(dyn.diagnostics[0]!.message).toMatch(/object literal of literal defaults/);
});
});
+
+/**
+ * `@compiled` does not change what the subset takes; it changes who has to act.
+ * An unmarked refusal is §3.2's design. A marked one is a build error.
+ */
+describe('a promise the author wrote down', () => {
+ it('sees the marker, and only where it was written', () => {
+ expect(result.required).toEqual(['FixturePromised', 'FixturePromiseKept']);
+ });
+
+ it('makes the same refusal an error, with the same reason and line', () => {
+ const promised = diagOf('FixturePromised')!;
+ const unmarked = diagOf('FixtureTrig')!;
+ expect(promised.severity).toBe('error');
+ expect(unmarked.severity).toBe('note');
+ // The marker is not a second rule: both are refused for the same reason.
+ expect(promised.message).toMatch(/Math\.cos is not exactly specified/);
+ expect(promised.kind).toBe(unmarked.kind);
+ expect(promised.line).toBeGreaterThan(0);
+ });
+
+ it('a kept promise is not a broken one', () => {
+ expect(compiled('FixturePromiseKept')).toBe(true);
+ expect(brokenPromises(result).map((d) => d.system)).toEqual(['FixturePromised']);
+ });
+});
diff --git a/examples/ecs-basics/src/systems/move.ts b/examples/ecs-basics/src/systems/move.ts
index 61fce6e98..2b87f63d7 100644
--- a/examples/ecs-basics/src/systems/move.ts
+++ b/examples/ecs-basics/src/systems/move.ts
@@ -3,6 +3,13 @@ import {
} from 'esengine';
import { Mover } from '../components';
+/**
+ * Moves every entity by its direction and speed, once per frame.
+ *
+ * @compiled
+ * A promise, not a hint: anything the subset cannot lower is a build error here
+ * rather than a silent fall back to the interpreter (REARCH_AOT_ABI.md §4.1).
+ */
export const moveSystem = defineSystem(
[Query(Mut(Transform), Mover), Res(Time)],
(query, time) => {