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
fix(bindings): a binding says what it is for, and the census holds both answers
esengined2ad0ff2764f
diff --git a/sdk/tests/binding-surface.test.ts b/sdk/tests/binding-surface.test.tsindex 11dc207df..84bf11056 100644--- a/sdk/tests/binding-surface.test.ts+++ b/sdk/tests/binding-surface.test.ts@@ -33,6 +33,10 @@import { describe, it, expect } from 'vitest';import { readFileSync, existsSync } from 'node:fs';import { resolve } from 'node:path';+import {+ DISPOSITIONS, TEST_PROBE_BINDINGS, PROBE_GUARD, PROBE_HEADER,+ type TestProbeBinding,+} from '../../tools/bindingDispositions.mjs';const CPP = resolve(__dirname, '../../src/esengine');const SDK = resolve(__dirname, '../src');@@ -55,6 +59,21 @@ function stripComments(src: string): string {// C++ side: emscripten registration parsing// =============================================================================+/**+ * Registration names inside `#ifdef <macro>` … `#endif` blocks. What keeps a+ * probe out of a release build is the guard, so a census row claiming one is+ * checked against the preprocessor rather than against its own say-so.+ */+function parseGuardedRegistrations(cppSource: string, macro: string): Set<string> {+ const src = stripComments(cppSource);+ const out = new Set<string>();+ const re = new RegExp(`#if(?:def)?\\s+${macro}\\b([\\s\\S]*?)#endif`, 'g');+ for (let m = re.exec(src); m; m = re.exec(src)) {+ for (const name of parseFunctionRegistrations(m[1])) out.add(name);+ }+ return out;+}+/** All `emscripten::function("name", ...)` registration names in a file. */function parseFunctionRegistrations(cppSource: string): Set<string> {const out = new Set<string>();@@ -282,6 +301,10 @@ const allDeclared = new Set([...moduleDeclared, ...tilemapDeclared]);// Emscripten-runtime exports declared for ergonomics; not embind registrations.const RUNTIME_EXPORTS = new Set(['_malloc', '_free']);+/** The census: which registrations are deliberately not production. */+const probeDeclared = new Set<string>(TEST_PROBE_BINDINGS.map((b: TestProbeBinding) => b.id));+const probeGuarded = parseGuardedRegistrations(webSdkEntry, PROBE_GUARD);+describe('WASM binding surface: module functions (hand-written mirror handshake)', () => {it('every TS-declared ESEngineModule function is a real registration (no phantom decls)', () => {const phantom = missingFrom(@@ -302,8 +325,50 @@ describe('WASM binding surface: module functions (hand-written mirror handshake)});it('every hand-registered binding is declared in the TS surface (no unmirrored bindings)', () => {- const unmirrored = missingFrom(handRegistered, allDeclared);- expect(unmirrored, `registered in WebSDKEntry/TilemapBindings but declared in no TS interface: ${unmirrored.join(', ')}`)+ // Minus the ones a census declares are not production. `production` is the+ // default, so an unlisted binding is still held to the strict rule.+ const production = [...handRegistered].filter((n) => !probeDeclared.has(n));+ const unmirrored = missingFrom(production, allDeclared);+ expect(unmirrored, `registered in WebSDKEntry/TilemapBindings but declared in no TS interface`+ + ` (and not declared a test-probe in tools/bindingDispositions.mjs): ${unmirrored.join(', ')}`)+ .toEqual([]);+ });++ it('a test-probe binding stays OUT of the production TS surface', () => {+ const leaked = [...probeDeclared].filter((n) => allDeclared.has(n));+ expect(leaked, `declared test-probe in tools/bindingDispositions.mjs but present in the`+ + ` shipping TS surface, which is a release ABI: ${leaked.join(', ')}`)+ .toEqual([]);+ });++ it('a test-probe binding is registered behind the probe guard', () => {+ const unguarded = [...probeDeclared].filter((n) => !probeGuarded.has(n));+ expect(unguarded, `declared test-probe but registered outside #ifdef ${PROBE_GUARD},`+ + ` so a release build would export it: ${unguarded.join(', ')}`)+ .toEqual([]);+ });++ it('a test-probe binding is declared in the probe-only header', () => {+ const probeHeader = read(resolve(CPP, PROBE_HEADER));+ const misplaced = [...probeDeclared].filter((n) => !new RegExp(`\\b${n}\\s*\\(`).test(probeHeader));+ expect(misplaced, `declared test-probe but not declared in ${PROBE_HEADER} — the header`+ + ` tool reads the shipping ones and does not read #ifdef: ${misplaced.join(', ')}`)+ .toEqual([]);+ });++ it('every declared test-probe still exists (no stale disposition)', () => {+ const gone = [...probeDeclared].filter((n) => !handRegistered.has(n));+ expect(gone, `declared test-probe in tools/bindingDispositions.mjs but registered nowhere;`+ + ` a disposition outliving its binding reads as an answered question: ${gone.join(', ')}`)+ .toEqual([]);+ });++ it('every disposition class the census uses is one this contract defines', () => {+ const classes = Object.keys(DISPOSITIONS);+ expect(classes, 'the census must define production and test-probe')+ .toEqual(expect.arrayContaining(['production', 'test-probe']));+ const unexplained = TEST_PROBE_BINDINGS.filter((b: TestProbeBinding) => !b.why);+ expect(unexplained.map((b: TestProbeBinding) => b.id), 'a test-probe row owes a `why`').toEqual([]);});});diff --git a/tools/bindingDispositions.d.mts b/tools/bindingDispositions.d.mtsnew file mode 100644index 000000000..7d5f2ce5d--- /dev/null+++ b/tools/bindingDispositions.d.mts@@ -0,0 +1,20 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/** Types for bindingDispositions.mjs, which the SDK's binding handshake reads. */++export declare const PROBE_GUARD: string;+export declare const PROBE_HEADER: string;++export interface BindingDisposition {+ inProductionSurface: boolean;+ means: string;+}++export declare const DISPOSITIONS: Record<string, BindingDisposition>;++export interface TestProbeBinding {+ id: string;+ why: string;+}++export declare const TEST_PROBE_BINDINGS: TestProbeBinding[];diff --git a/tools/bindingDispositions.mjs b/tools/bindingDispositions.mjsnew file mode 100644index 000000000..f399b58e7--- /dev/null+++ b/tools/bindingDispositions.mjs@@ -0,0 +1,65 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file bindingDispositions.mjs — what each hand-registered wasm binding is FOR.+ *+ * Two gates were each right and together impossible to satisfy. The binding+ * handshake says every `emscripten::function` registration must be mirrored by a+ * declaration in the production TS surface; the test-probe rule says an adapter+ * that exists only to be measured must never reach a release ABI. A binding that+ * is both — registered, and deliberately absent from `ESEngineModule` — had no+ * legal shape, and the handshake simply failed.+ *+ * The census that resolves it is not a list of excused names. It is a class per+ * binding, and each class owes obligations a gate can check:+ *+ * production must be declared in the production TS surface+ * test-probe must NOT be; must be registered behind the probe guard, and+ * must be declared in the probe-only header+ *+ * `production` is the DEFAULT, so nothing has to be listed to be held to the+ * strict rule and a new binding cannot slip in unmirrored. Only the exception+ * is enumerated, which is what keeps this from becoming a list of things+ * somebody once wanted to stop failing.+ */++/** The guard a probe-only registration must sit behind, and the header its+ * declaration must live in — both are what keep it out of a release build. */+export const PROBE_GUARD = 'ES_ENABLE_TEST_PROBES';+export const PROBE_HEADER = 'bindings/TestProbeBindings.hpp';++export const DISPOSITIONS = {+ production: {+ inProductionSurface: true,+ means: 'a capability the shipping SDK calls; the TS surface is its contract',+ },+ 'test-probe': {+ inProductionSurface: false,+ means: 'an adapter that exists to be measured or cross-checked, never shipped',+ },+};++/**+ * Every binding that is NOT production, and why.+ *+ * `why` is owed: a class alone is a label, and the sentence beside it says what+ * a later reader checks it against — above all whether the thing it measures has+ * acquired a production consumer, the moment a probe should stop being one.+ */+export const TEST_PROBE_BINDINGS = [+ {+ id: 'engine_prewarmMeshVariants',+ why: 'the EQUIVALENCE oracle: it derives program requirements from live ECS'+ + ' entities so a test can check them against what the prepared document'+ + ' derived. Production never has entities at that moment — the whole point'+ + ' of preparing a cell is that it is readied before it has any — so this'+ + ' side exists only to be the independent judge of the other.',+ },+ {+ id: 'engine_prewarmMeshVariantsFromDocument',+ why: 'the document-side derivation, still probe-only while the residency'+ + ' lifecycle calls it from nowhere. It is the half with a production'+ + ' consumer coming, so when preparation starts requiring a readiness'+ + ' stamp this row is what has to be removed rather than amended.',+ },+];