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(gates): one list of static gates, and both scopes read it

esengine493cb8dc0005
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 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 tests
run: 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 — the
diff --git a/package.json b/package.json
index 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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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}`);