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(gates): one list of static gates, and both scopes read it
esengine493cb8dc0005
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 7f49db718..279e0439c 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -146,53 +146,15 @@ jobs:- uses: ./.github/actions/setup- - name: Check GL boundary (no gl* outside GLDevice)- run: node tools/check-gl-boundary.mjs-- - name: Check render-command boundary (DrawCommands built only by BatchBuilder)- run: node tools/check-draw-command-boundary.mjs-- # The release path has no pull request to fail on, so a workflow step that- # cannot run is found by pushing a tag. Checked here, where every push is.- - name: Check workflows (tooling steps install the workspace)- run: node tools/check-workflows.mjs-- # The device build's codegen, without the device build: it needs no compiler- # and takes a second, but nothing outside a release ran it — so a header that- # moved cost a full Dawn build to find out about, twice.- - name: Check native binding codegen (headers + the includes it generates)- run: node tools/check-native-bindings.mjs-- # Filtered so the SDK is checked by ITS OWN pinned TypeScript (the workspace- # carries two majors — desktop is on 6.x); a bare root `pnpm exec tsc`- # resolves an arbitrary compiler. Mirrors the repo's `verify` gate exactly.- - name: Type-check SDK- run: pnpm --filter ./sdk exec tsc --noEmit-- - name: Check API surface (snapshot + release-tag policy)- run: node tools/api-surface.mjs --check-- - name: Build SDK- run: pnpm --filter ./sdk build-- # The snapshot above is read out of the sources, so it says nothing about what- # the declaration build actually emitted. This is the only step that looks at- # the .d.ts a consumer installs.- - name: Check built declarations carry the API surface- run: node tools/api-surface.mjs --check-dts-- - name: Type-check Examples- run: node build-tools/cli.js check-examples-- - name: Validate prefab assets- run: node build-tools/cli.js validate-prefabs+ # Every static gate, from the one list in tools/gates.mjs. CI and the+ # pre-push hook used to enumerate their own — seventeen gates ran only on a+ # machine with the hook installed, and five only here.+ - name: Static gates+ run: node tools/run-gates.mjs --scope ci- name: Run SDK testsrun: pnpm --filter ./sdk exec vitest run- - name: Type-check Desktop- run: pnpm --filter @estella/editor exec tsc --noEmit-# The Android packaging tests check what we write against implementations that# are not ours. androguard decodes the binary manifest; bundletool is the App# Bundle format's own authority, and the runner has the JVM it needs — thediff --git a/package.json b/package.jsonindex b64324129..2d9f02001 100644--- a/package.json+++ b/package.json@@ -17,7 +17,7 @@"emsdk:setup": "node build-tools/toolchain/setup-emsdk.js","asset-meta": "node tools/asset-meta.js","migrate-asset-refs": "node tools/migrate-asset-refs.js",- "verify": "pnpm --filter ./sdk exec tsc --noEmit && pnpm --filter @estella/editor exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs && node tools/check-layers.mjs && node tools/check-project-settings.mjs && node tools/check-workflows.mjs && node tools/check-tool-calls.mjs && node tools/check-inspector-door.mjs && node tools/check-dirty-source.mjs && node tools/check-path-sandbox.mjs && node tools/check-key-codes.mjs && node tools/check-comment-style.mjs && node tools/check-cpp-tests.mjs && node tools/check-verifier-exit.mjs && node tools/check-render-scenes.mjs && node tools/check-release-metadata.mjs && node tools/check-golden.mjs && node tools/check-engine-gaps.mjs && node tools/check-minigame-host.mjs && node tools/check-release-gate.mjs && node tools/component-reference.mjs --check",+ "verify": "node tools/run-gates.mjs --scope local","perf": "node tools/perf-guard.mjs --check","scale": "node tools/perf-budget.mjs","stress-project": "node tools/stress-project.mjs",diff --git a/tools/check-workflows.mjs b/tools/check-workflows.mjsindex 17444f459..587d4e010 100644--- a/tools/check-workflows.mjs+++ b/tools/check-workflows.mjs@@ -22,6 +22,7 @@import { readdirSync, readFileSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';+import { GATES, SCOPES } from './gates.mjs';const WORKFLOWS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '.github', 'workflows');const SETUP = './.github/actions/setup';@@ -123,6 +124,32 @@ for (const file of readdirSync(WORKFLOWS).filter((f) => /\.ya?ml$/.test(f))) {}}+// The gate list is one list only while both scopes read it. A workflow that+// enumerates check-*.mjs steps of its own is the second list growing back.+const gateProblems = [];+for (const g of GATES) {+ if (g.where === undefined) continue;+ if (!SCOPES.includes(g.where)) gateProblems.push(`gate "${g.id}" has scope "${g.where}" (have: ${SCOPES.join(', ')})`);+ if (!(typeof g.why === 'string' && g.why.trim())) {+ gateProblems.push(`gate "${g.id}" runs in ${g.where} only, with no reason — say why the other scope cannot`);+ }+}+const ciYml = readFileSync(path.join(WORKFLOWS, 'build.yml'), 'utf8');+if (!ciYml.includes('run-gates.mjs')) {+ gateProblems.push('build.yml does not run tools/run-gates.mjs — CI would be back to a gate list of its own');+}+for (const g of GATES) {+ const own = g.run.match(/tools\/(check-[\w-]+\.mjs)/);+ if (own && ciYml.includes(own[1]) && g.where !== 'local') {+ gateProblems.push(`build.yml names ${own[1]} directly; run-gates already runs it for the ci scope`);+ }+}+if (gateProblems.length > 0) {+ console.error('\n✗ the static gate list does not hold up:\n');+ for (const p of gateProblems) console.error(` ${p}`);+ process.exit(1);+}+if (violations.length > 0) {console.error(`\n✗ ${violations.length} workflow step(s) run workspace tooling with no install:\n`);for (const v of violations) {@@ -135,3 +162,4 @@ if (violations.length > 0) {}console.log('✓ every workflow step that runs workspace tooling installs it first');+console.log(`✓ ${GATES.length} static gate(s) in one list; CI runs it through run-gates.mjs`);diff --git a/tools/gates.mjs b/tools/gates.mjsnew file mode 100644index 000000000..9a416616e--- /dev/null+++ b/tools/gates.mjs@@ -0,0 +1,74 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file gates.mjs — the static gates, in order, and where each one runs.+ *+ * There were two lists again. `pnpm run verify` (what the pre-push hook runs)+ * held eighteen gates and CI's Tests job held six, overlapping in one. So+ * seventeen gates only ever ran on a machine with the hook installed, and five+ * only ran in CI — which is how a push went out green and CI failed on+ * check-examples, and how every gate written this year could have been silently+ * skipped by pushing from anywhere else.+ *+ * One ordered list, then, with `where` saying which scope pays for each. Order+ * is load-bearing: the declaration checks and the example type-check both read+ * what `sdk-build` emits.+ */++/** Scopes a gate can run in. `both` is the default and needs no excuse. */+export const SCOPES = ['local', 'ci'];++/**+ * `run` is a shell command from the repo root. `where` narrows a gate to one+ * scope and then owes a `why` — a gate that quietly runs in one place is the+ * thing this file exists to stop.+ */+export const GATES = [+ { id: 'tsc-sdk', run: 'pnpm --filter ./sdk exec tsc --noEmit' },+ { id: 'tsc-editor', run: 'pnpm --filter @estella/editor exec tsc --noEmit' },+ { id: 'gl-boundary', run: 'node tools/check-gl-boundary.mjs' },+ { id: 'draw-command-boundary', run: 'node tools/check-draw-command-boundary.mjs' },+ {+ id: 'native-bindings',+ run: 'node tools/check-native-bindings.mjs',+ where: 'ci',+ why: 'the EHT generator shells out to `python`, which macOS does not ship a runnable one of; run it by hand where you have one',+ },+ { id: 'api-surface', run: 'node tools/api-surface.mjs --check' },+ // Everything below reads what this emits: the declaration snapshot compares+ // against the built .d.ts, and the examples type-check against dist.+ { id: 'sdk-build', run: 'pnpm --filter ./sdk build' },+ { id: 'api-surface-dts', run: 'node tools/api-surface.mjs --check-dts' },+ { id: 'cycles', run: 'node tools/check-cycles.mjs' },+ { id: 'layers', run: 'node tools/check-layers.mjs' },+ { id: 'project-settings', run: 'node tools/check-project-settings.mjs' },+ { id: 'workflows', run: 'node tools/check-workflows.mjs' },+ { id: 'tool-calls', run: 'node tools/check-tool-calls.mjs' },+ { id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },+ { id: 'dirty-source', run: 'node tools/check-dirty-source.mjs' },+ { id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },+ { id: 'key-codes', run: 'node tools/check-key-codes.mjs' },+ { id: 'comment-style', run: 'node tools/check-comment-style.mjs' },+ {+ id: 'cpp-tests',+ run: 'node tools/check-cpp-tests.mjs',+ where: 'local',+ why: 'it configures and builds a native cmake tree; CI compiles and RUNS those harnesses in its own C++ jobs',+ },+ { id: 'verifier-exit', run: 'node tools/check-verifier-exit.mjs' },+ { id: 'render-scenes', run: 'node tools/check-render-scenes.mjs' },+ { id: 'release-metadata', run: 'node tools/check-release-metadata.mjs' },+ { id: 'golden', run: 'node tools/check-golden.mjs' },+ { id: 'engine-gaps', run: 'node tools/check-engine-gaps.mjs' },+ { id: 'minigame-host', run: 'node tools/check-minigame-host.mjs' },+ { id: 'release-gate', run: 'node tools/check-release-gate.mjs' },+ { id: 'component-reference', run: 'node tools/component-reference.mjs --check' },+ { id: 'examples', run: 'node build-tools/cli.js check-examples' },+ { id: 'prefabs', run: 'node build-tools/cli.js validate-prefabs' },+];++/** The gates a scope runs, in declaration order. */+export function gatesFor(scope) {+ if (!SCOPES.includes(scope)) throw new Error(`unknown scope "${scope}" (have: ${SCOPES.join(', ')})`);+ return GATES.filter((g) => !g.where || g.where === scope);+}diff --git a/tools/run-gates.mjs b/tools/run-gates.mjsnew file mode 100644index 000000000..425c59c7d--- /dev/null+++ b/tools/run-gates.mjs@@ -0,0 +1,48 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file run-gates.mjs — run the static gates a scope pays for.+ *+ * Stops at the first failure on purpose: the gates are ordered, and a later one+ * reading a build an earlier one failed to produce reports a second, invented+ * problem on top of the real one.+ *+ * node tools/run-gates.mjs --scope local+ * node tools/run-gates.mjs --scope ci+ */+import { spawnSync } from 'node:child_process';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { SCOPES, GATES, gatesFor } from './gates.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const argv = process.argv.slice(2);+const flag = (n, d) => {+ const i = argv.indexOf(`--${n}`);+ return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d;+};++const SCOPE = flag('scope', 'local');+if (!SCOPES.includes(SCOPE)) {+ console.error(`run-gates: unknown scope "${SCOPE}" (have: ${SCOPES.join(', ')})`);+ process.exit(2);+}++const gates = gatesFor(SCOPE);+const skipped = GATES.filter((g) => g.where && g.where !== SCOPE);+console.log(`gates ${SCOPE}: ${gates.length} of ${GATES.length}`);++for (const gate of gates) {+ const r = spawnSync('sh', ['-c', gate.run], { cwd: ROOT, stdio: 'inherit' });+ if (r.status !== 0) {+ console.error(`\n✗ ${gate.id} — \`${gate.run}\``);+ // Naming what did NOT run matters at the moment of failure: the gates after+ // this one said nothing, and a reader should not take silence for green.+ const after = gates.slice(gates.indexOf(gate) + 1);+ if (after.length) console.error(` ${after.length} later gate(s) did not run: ${after.map((g) => g.id).join(', ')}`);+ process.exit(r.status ?? 1);+ }+}++console.log(`\ngates ${SCOPE}: ${gates.length}/${gates.length} green`);+for (const g of skipped) console.log(` not in this scope: ${g.id} — ${g.why}`);