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.

build(gates): a cost dimension for the gate list, and a runner for the release one

yhhe86230665259
diff --git a/.githooks/pre-push b/.githooks/pre-push
index b162559aa..4db3e5456 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -1,12 +1,21 @@
#!/bin/sh
-# Pre-push guard: run the cheap CI static gates locally so a public-API surface
-# drift (a changed export without a refreshed sdk/etc/*.api.md snapshot) is caught
-# before it reddens master — not after, as a follow-up fix commit. Mirrors the
-# fast checks in the CI "Tests" job; keep it to seconds so pushing stays cheap.
-if ! pnpm run verify; then
+# Pre-push guard: run the STATIC gates locally so a public-API surface drift (a
+# changed export without a refreshed sdk/etc/*.api.md snapshot) is caught before
+# it reddens master — not after, as a follow-up fix commit.
+#
+# Not the test suites. `verify:push` is `verify --no-suites`: the same one ordered
+# list in tools/gates.mjs, minus the five gates that RUN a suite, which CI runs on
+# this very push and which cost minutes here to answer a question that is about to
+# be answered anyway. The suites also fail on a stale local build/wasm/web — an
+# artifact CI builds fresh — so on this path they reported the machine, not the
+# push, and being early in the list they stranded every gate behind them.
+#
+# `pnpm run verify` still means everything; only the hook stopped paying for it.
+if ! pnpm run verify:push; then
echo ''
echo '✗ push blocked by pre-push verify.'
echo ' API surface drifted? node tools/api-surface.mjs --update (then commit the refreshed sdk/etc/*.api.md)'
+ echo ' Suites are not in this hook — run `pnpm run verify` for the full list.'
echo ' To bypass in a real emergency: git push --no-verify'
exit 1
fi
diff --git a/package.json b/package.json
index 66b5d4c3b..597d32b7e 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
"asset-meta": "node tools/asset-meta.js",
"migrate-asset-refs": "node tools/migrate-asset-refs.js",
"verify": "node tools/run-gates.mjs --scope local",
+ "verify:push": "node tools/run-gates.mjs --scope local --no-suites",
"perf": "node tools/perf-guard.mjs --check",
"scale": "node tools/perf-budget.mjs",
"stress-project": "node tools/stress-project.mjs",
@@ -26,6 +27,7 @@
"soak": "pnpm --filter ./sdk exec vitest run tests/soak",
"torture": "pnpm --filter ./sdk exec vitest run tests/torture",
"gate": "node tools/check-release-gate.mjs --report",
+ "gate:run": "node tools/run-release-gate.mjs",
"render-host": "node tools/render-host/build.mjs",
"verify:render": "node tools/verify-render.mjs",
"test": "vitest run --config vitest.engine.config.ts",
diff --git a/tools/gates.mjs b/tools/gates.mjs
index fd80aa8fb..e16fe10fe 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -3,7 +3,7 @@
/**
* @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)
+ * There were two lists again. `pnpm run verify` (which the pre-push hook ran)
* 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
@@ -31,6 +31,11 @@ export const SCOPES = ['local', 'ci'];
* "the full gate suite is green" mean something: check-verification-authority
* compares the claim against the directories that HOLD tests, so a suite nothing
* invokes is a finding rather than a silence.
+ *
+ * `covers` is also the COST dimension: the gates that run a suite are the ones
+ * that cost minutes, so `--no-suites` drops exactly those. Orthogonal to `where`
+ * — that says a gate CANNOT run here, this says a caller is not paying now — so
+ * the list above stays the only list, and a dropped suite is still named.
*/
export const GATES = [
{ id: 'tsc-sdk', run: 'pnpm --filter ./sdk exec tsc --noEmit' },
@@ -219,7 +224,9 @@ export const GATES = [
];
/** The gates a scope runs, in declaration order. `hasEditor` gates the editor ones. */
-export function gatesFor(scope, hasEditor = true) {
+export function gatesFor(scope, hasEditor = true, { suites = true } = {}) {
if (!SCOPES.includes(scope)) throw new Error(`unknown scope "${scope}" (have: ${SCOPES.join(', ')})`);
- return GATES.filter((g) => (!g.where || g.where === scope) && (hasEditor || g.needs !== 'editor'));
+ return GATES.filter((g) => (!g.where || g.where === scope)
+ && (hasEditor || g.needs !== 'editor')
+ && (suites || !g.covers?.length));
}
diff --git a/tools/run-gates.mjs b/tools/run-gates.mjs
index 7fa546e97..bd3bcedc8 100644
--- a/tools/run-gates.mjs
+++ b/tools/run-gates.mjs
@@ -33,8 +33,14 @@ if (!SCOPES.includes(SCOPE)) {
// cannot run without it. Named below rather than silently dropped — a gate that
// disappears quietly is the same as one that always passes.
const HAS_EDITOR = existsSync(path.join(ROOT, 'desktop', 'package.json'));
-const gates = gatesFor(SCOPE, HAS_EDITOR);
+// --no-suites drops the gates that RUN a suite (the `covers` ones), for a caller
+// that is not paying minutes right now — the pre-push hook. Everything else,
+// including the builds the later gates read, still runs.
+const SUITES = !argv.includes('--no-suites');
+const gates = gatesFor(SCOPE, HAS_EDITOR, { suites: SUITES });
const skipped = GATES.filter((g) => g.where && g.where !== SCOPE);
+/** Suites this run is not paying for — named, never silently absent. */
+const unpaid = SUITES ? [] : gatesFor(SCOPE, HAS_EDITOR).filter((g) => g.covers?.length);
const noEditor = HAS_EDITOR ? [] : GATES.filter((g) => g.needs === 'editor' && (!g.where || g.where === SCOPE));
console.log(`gates ${SCOPE}: ${gates.length} of ${GATES.length}`);
if (noEditor.length) {
@@ -67,10 +73,20 @@ function reportSuites() {
if (unrun.length) {
console.log(` test suites NOT run: ${unrun.map((g) => g.id).join(', ')} — no editor checkout`);
}
+ // The whole point of --no-suites is that it is CHEAP, not that it is quiet.
+ if (unpaid.length) {
+ console.log(` test suites NOT run: ${unpaid.map((g) => g.id).join(', ')} — --no-suites; CI runs them`);
+ }
}
+/** What each gate cost, so the expensive ones are a measurement rather than a
+ * hunch — this list is ordered by hand and nothing was timing it. */
+const spent = [];
+
for (const gate of gates) {
+ const began = Date.now();
const r = spawnSync('sh', ['-c', gate.run], { cwd: ROOT, stdio: 'inherit' });
+ spent.push({ id: gate.id, ms: Date.now() - began });
// A shell that would not start is not a gate that failed. Reported as one it
// sends the reader after the first gate's subject, which said nothing at all.
if (r.error) {
@@ -89,6 +105,11 @@ for (const gate of gates) {
}
console.log(`\ngates ${SCOPE}: ${gates.length}/${gates.length} green`
+ + ` in ${(spent.reduce((t, g) => t + g.ms, 0) / 1000).toFixed(0)}s`
+ (noEditor.length ? ` (${noEditor.length} editor gate(s) had no checkout to run against)` : ''));
+// Name the costliest: "the gates are slow" is not something anyone can act on,
+// and "sdk-tests took 78 of the 210 seconds" is.
+const dear = [...spent].sort((x, y) => y.ms - x.ms).slice(0, 5);
+console.log(` costliest: ${dear.map((g) => `${g.id} ${(g.ms / 1000).toFixed(0)}s`).join(', ')}`);
reportSuites();
for (const g of skipped) console.log(` not in this scope: ${g.id} — ${g.why}`);
diff --git a/tools/run-release-gate.mjs b/tools/run-release-gate.mjs
new file mode 100644
index 000000000..2d75fe816
--- /dev/null
+++ b/tools/run-release-gate.mjs
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file run-release-gate — run the exit criteria, and say what they answered.
+ *
+ * releaseGate.mjs ends with "this says the criteria are OWNED; whether they PASS
+ * is what running them says" — and nothing ran them. The list had the half that
+ * check-release-gate polices (every criterion still has a command) and not the
+ * half that reports a verdict, so the only runner was a person typing 27
+ * commands. hot-update-lands-or-rolls-back was deterministically broken for
+ * days behind that gap.
+ *
+ * This is run-gates.mjs for the release list, and deliberately its twin: one
+ * ordered list, a runner over it, and everything it did NOT run said out loud.
+ *
+ * node tools/run-release-gate.mjs # run them
+ * node tools/run-release-gate.mjs --plan # what would run, and what cannot
+ * node tools/run-release-gate.mjs --only golden,aot
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RELEASE, CRITERIA } from './releaseGate.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+const flag = (name) => {
+ const i = argv.indexOf(`--${name}`);
+ return i >= 0 ? argv[i + 1] : null;
+};
+const ONLY = flag('only')?.split(',').map((s) => s.trim()).filter(Boolean) ?? null;
+
+const automated = CRITERIA.filter((c) => c.answeredBy)
+ .filter((c) => !ONLY || ONLY.some((o) => c.id.includes(o)));
+const manual = CRITERIA.filter((c) => c.manual);
+
+/**
+ * One run per COMMAND, not per criterion: five criteria name
+ * `verify-golden --tier release` and three name the AOT frame bench, and paying
+ * for each of them separately would say the same thing five times and cost five
+ * times as much. The verdict is attributed back to every criterion that asked.
+ */
+const jobs = [];
+for (const c of automated) {
+ const at = jobs.find((j) => j.run === c.answeredBy);
+ if (at) at.ids.push(c.id);
+ else jobs.push({ run: c.answeredBy, ids: [c.id] });
+}
+
+console.log(`release gate ${RELEASE}: ${automated.length} criteria in ${jobs.length} command(s)`
+ + (ONLY ? ` (--only ${ONLY.join(',')})` : ''));
+
+if (argv.includes('--plan')) {
+ for (const j of jobs) console.log(` ${j.ids.join(', ')}\n ${j.run}`);
+ for (const m of manual) console.log(` BY HAND ${m.id} — ${m.manual}`);
+ process.exit(0);
+}
+
+// Every criterion, not the first failure: which of them a release is short of is
+// the useful answer, and stopping early turns the rest into silence — the same
+// reason verify-render reports its whole matrix.
+const failed = [];
+for (const j of jobs) {
+ const began = Date.now();
+ process.stdout.write(`\n=== ${j.ids.join(', ')}\n ${j.run}\n`);
+ const r = spawnSync('sh', ['-c', j.run], { cwd: ROOT, stdio: 'inherit' });
+ const secs = ((Date.now() - began) / 1000).toFixed(0);
+ if (r.error) {
+ console.error(`✗ could not run it: ${r.error.message}`);
+ failed.push({ ...j, secs, why: 'would not start' });
+ } else if (r.status !== 0) {
+ console.error(`✗ FAIL (${secs}s)`);
+ failed.push({ ...j, secs, why: `exit ${r.status}` });
+ } else {
+ console.log(`✓ PASS (${secs}s)`);
+ }
+}
+
+const short = failed.flatMap((j) => j.ids);
+console.log(`\nrelease gate ${RELEASE}: ${automated.length - short.length}/${automated.length} criteria answered`);
+for (const j of failed) console.log(` ✗ ${j.ids.join(', ')} — ${j.why}`);
+// Named, always: a release is not ready because 27 commands went green, and a
+// summary that omits the four nobody can automate reads as though it is.
+console.log(` ${manual.length} criteria are BY HAND and this cannot answer them:`);
+for (const m of manual) console.log(` ${m.id} — ${m.manual}`);
+process.exit(short.length ? 1 : 0);