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(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.json
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.ts
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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',