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(api): a frozen signature may only be spelled in frozen types
yhh19d1fa1a5c65
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex e75b58eeb..a0cd572f7 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 6,"beta": 24,- "experimental": 1594,+ "experimental": 1595,"deprecated": 1},- "total": 1624,+ "total": 1625,"public": [{"name": "Commands",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex a20990b97..a2906514f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 6 public · 17 beta · 1482 experimental · 1 deprecated+Symbols: 6 public · 17 beta · 1483 experimental · 1 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -5712,6 +5712,11 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```+## QueryArg — type @experimental+```+AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>+```+## QueryBuilder — interface @experimental```_addedFilters: { index: number; component: AnyComponentDef; }[]diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex e81ab2a48..a8b2e6591 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 6 public · 22 beta · 1501 experimental · 1 deprecated+Symbols: 6 public · 22 beta · 1502 experimental · 1 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -5895,6 +5895,11 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```+## QueryArg — type @experimental+```+AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>+```+## QueryBuilder — interface @experimental```_addedFilters: { index: number; component: AnyComponentDef; }[]diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 13e657634..57ac016cc 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 6 public · 19 beta · 1481 experimental · 1 deprecated+Symbols: 6 public · 19 beta · 1482 experimental · 1 deprecated## ANCHOR_AXES — const @experimental```@@ -5707,6 +5707,11 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```+## QueryArg — type @experimental+```+AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>+```+## QueryBuilder — interface @experimental```_addedFilters: { index: number; component: AnyComponentDef; }[]diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 71f14762f..965c36252 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 6 public · 17 beta · 1502 experimental · 1 deprecated+Symbols: 6 public · 17 beta · 1503 experimental · 1 deprecated## ANCHOR_AXES — const @experimental```@@ -5952,6 +5952,11 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```+## QueryArg — type @experimental+```+AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>+```+## QueryBuilder — interface @experimental```_addedFilters: { index: number; component: AnyComponentDef; }[]diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 31314ec90..8aa3d8608 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 6 public · 17 beta · 1492 experimental · 1 deprecated+Symbols: 6 public · 17 beta · 1493 experimental · 1 deprecated## ANCHOR_AXES — const @experimental```@@ -5714,6 +5714,11 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```+## QueryArg — type @experimental+```+AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>+```+## QueryBuilder — interface @experimental```_addedFilters: { index: number; component: AnyComponentDef; }[]diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 962f41a51..56c443bac 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -267,6 +267,7 @@ export {QueryInstance,RemovedQueryInstance,type FilterExpr,+ type QueryArg,type QueryBuilder,type QueryDescriptor,type QueryResult,diff --git a/tools/check-tier-leaks.mjs b/tools/check-tier-leaks.mjsnew file mode 100644index 000000000..9466d83c1--- /dev/null+++ b/tools/check-tier-leaks.mjs@@ -0,0 +1,121 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-tier-leaks.mjs — a frozen signature that names an unfrozen type.+ *+ * `@public` promises a shape. If that shape is spelled with a type nobody froze,+ * the promise is only as good as the weakest name in it: the symbol survives+ * 1.0 and the type it hands you does not. So a frozen symbol may only name+ * frozen types.+ *+ * Wave 1 froze six symbols whose signatures are spelled in a vocabulary nobody+ * has frozen yet, so this starts as a ratchet rather than a wall: the leaks that+ * exist are named in {@link ACCEPTED} and a new one fails. Each line deleted+ * from that list is a promise that got real.+ *+ * node tools/check-tier-leaks.mjs exit 1 on an undeclared leak+ * node tools/check-tier-leaks.mjs --report print what freezing would cost+ */+import { readFileSync, existsSync } from 'node:fs';+import { join } from 'node:path';+import { ETC, ENTRIES } from './lib/sdkProgram.mjs';+import { parseSnapshot } from './lib/apiSnapshot.mjs';++/**+ * Frozen symbols known to name unfrozen types, and what is still missing. Every+ * one is the ECS vocabulary the six Wave 1 symbols are written in — descriptors,+ * defs and the parameter union — none of which has been through the freeze bar.+ */+export const ACCEPTED = {+ Commands: 'the descriptor it returns is unfrozen ECS vocabulary',+ Mut: 'the component-def union and wrapper are unfrozen ECS vocabulary',+ Query: 'the argument union and builder are unfrozen ECS vocabulary',+ Res: 'the resource def and descriptor are unfrozen ECS vocabulary',+ defineComponent: 'the component def and its metadata are unfrozen ECS vocabulary',+ defineSystem: 'the system def, params and options are unfrozen ECS vocabulary',+};++/** Every symbol across every entry, keeping the strongest tier any entry gives it. */+function surface() {+ const rank = { public: 0, beta: 1, experimental: 2, unclaimed: 3 };+ const out = new Map();+ for (const entryName of Object.keys(ENTRIES)) {+ const file = join(ETC, `${entryName}.api.md`);+ if (!existsSync(file)) continue;+ for (const [name, s] of parseSnapshot(readFileSync(file, 'utf8'))) {+ const seen = out.get(name);+ if (!seen) { out.set(name, { ...s }); continue; }+ if ((rank[s.tier] ?? 9) < (rank[seen.tier] ?? 9)) seen.tier = s.tier;+ if (s.body.length > seen.body.length) seen.body = s.body;+ }+ }+ return out;+}++const api = surface();++/** Exported symbols a body names. A type not in the surface is a built-in or private. */+function referenced(name) {+ const body = api.get(name)?.body ?? '';+ const out = new Set();+ for (const id of body.match(/[A-Za-z_$][\w$]*/g) ?? []) {+ if (id !== name && api.has(id)) out.add(id);+ }+ return out;+}++const frozen = [...api].filter(([, s]) => s.tier === 'public').map(([n]) => n);+if (frozen.length === 0) {+ console.log('check-tier-leaks: nothing is @public yet.');+ process.exit(0);+}++const leaks = new Map();+for (const name of frozen) {+ const weak = [...referenced(name)].filter((r) => api.get(r).tier !== 'public').sort();+ if (weak.length) leaks.set(name, weak);+}++if (process.argv.includes('--report')) {+ // What freezing these WOULD cost: the closure, since each type dragged in+ // names types of its own.+ const closure = new Set();+ const queue = [...leaks.values()].flat();+ while (queue.length) {+ const n = queue.pop();+ if (closure.has(n) || api.get(n)?.tier === 'public') continue;+ closure.add(n);+ for (const r of referenced(n)) if (!closure.has(r) && api.get(r).tier !== 'public') queue.push(r);+ }+ console.log(`# ${frozen.length} @public symbol(s), ${leaks.size} leaking\n`);+ for (const [name, weak] of [...leaks].sort()) {+ console.log(`${name}\n ${weak.map((w) => `${w} (@${api.get(w).tier})`).join('\n ')}`);+ }+ const kinds = {};+ for (const n of closure) kinds[api.get(n).kind] = (kinds[api.get(n).kind] ?? 0) + 1;+ console.log(`\n# closure: ${closure.size} symbol(s) would have to be frozen too`);+ console.log(Object.entries(kinds).sort((a, b) => b[1] - a[1]).map(([k, v]) => ` ${v} ${k}`).join('\n'));+ process.exit(0);+}++const undeclared = [...leaks].filter(([name]) => !ACCEPTED[name]);+const stale = Object.keys(ACCEPTED).filter((name) => !leaks.has(name));++if (undeclared.length === 0 && stale.length === 0) {+ console.log(`check-tier-leaks: ${frozen.length} @public symbol(s), ${leaks.size} leaking and declared.`);+ for (const [name, weak] of [...leaks].sort()) {+ console.log(` ${name} — ${weak.map((w) => `${w} @${api.get(w).tier}`).join(', ')}`);+ }+ process.exit(0);+}++for (const [name, weak] of undeclared.sort()) {+ console.error(` ${name} — names ${weak.map((w) => `${w} (@${api.get(w).tier})`).join(', ')}`);+}+for (const name of stale) {+ console.error(` ${name} — listed in ACCEPTED but leaks nothing now; delete the line`);+}+console.error(`\ncheck-tier-leaks: ${undeclared.length} undeclared leak(s), ${stale.length} stale exemption(s).`);+console.error('A frozen symbol may only name frozen types. Freeze them, or declare the gap in ACCEPTED.');+process.exit(1);diff --git a/tools/gates.mjs b/tools/gates.mjsindex 36cc0ad7e..905550b41 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -38,6 +38,7 @@ export const GATES = [// last release tag shipped — drift says the surface moved, this says a promise did.{ id: 'api-surface-baseline', run: 'node tools/api-surface.mjs --check-baseline' },{ id: 'freeze-bar', run: 'node tools/check-freeze-bar.mjs' },+ { id: 'tier-leaks', run: 'node tools/check-tier-leaks.mjs' },// Everything below reads what this emits: the declaration snapshot, the// editor's own type-check and the examples all resolve `esengine` from dist.{ id: 'sdk-build', run: 'pnpm --filter ./sdk build' },diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjsindex e0481500c..0d5d34591 100644--- a/tools/releaseGate.mjs+++ b/tools/releaseGate.mjs@@ -164,6 +164,12 @@ export const CRITERIA = [answeredBy: 'node tools/api-surface.mjs --check-baseline',needs: ['tools/api-surface.mjs', 'tools/lib/apiSnapshot.mjs'],},+ {+ id: 'frozen-api-spelled-in-frozen-types',+ says: 'no @public signature names a type at a weaker tier except where the gap is declared',+ answeredBy: 'node tools/check-tier-leaks.mjs',+ needs: ['tools/check-tier-leaks.mjs'],+ },{id: 'tiers-reach-the-creator',says: 'the stability tier is in the .d.ts a project compiles against, not only in our snapshot',