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): a push runs the suites its own change owes

esenginec75f4de51148
diff --git a/.githooks/pre-push b/.githooks/pre-push
index 4db3e5456..d2d52d3fe 100755
--- a/.githooks/pre-push
+++ b/.githooks/pre-push
@@ -3,19 +3,24 @@
# 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.
+# And the test suites a change OWES. `verify:push` is `verify --suites owed`: the
+# same one ordered list in tools/gates.mjs, running the suites whose `owns` this
+# push has touched and leaving the rest to CI. Paying for none of them was cheap
+# and wrong — a tool gained a call, the double that stands in for it in the editor
+# suite did not, and the push went out red because no suite on this path compares
+# the two. Typically one suite runs, and the whole set is 80s.
#
-# `pnpm run verify` still means everything; only the hook stopped paying for it.
+# A machine that cannot run an owed suite is not excused here: the suite says what
+# it needs (an engine build, an emsdk) and this stops. Building it, or declaring
+# the gap the way CI does, is the answer — a suite quietly downgraded to a partial
+# run is the thing check-suite-preconditions exists to refuse.
+#
+# `pnpm run verify` still means everything; the hook pays for what it changed.
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 ' Only the suites this change OWES ran — `pnpm run verify` runs all five.'
echo ' To bypass in a real emergency: git push --no-verify'
exit 1
fi
diff --git a/package.json b/package.json
index b86b4c1b6..211b52d11 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +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",
+ "verify:push": "node tools/run-gates.mjs --scope local --suites owed",
"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-suite-ownership.mjs b/tools/check-suite-ownership.mjs
new file mode 100644
index 000000000..28f8b8a2a
--- /dev/null
+++ b/tools/check-suite-ownership.mjs
@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-suite-ownership.mjs — every suite says what SOURCE it answers for,
+ * and that claim resolves.
+ *
+ * `covers` made "the gate list is green" mean something by naming the tests a
+ * suite runs. `owns` is the other direction — the source whose direct unit-test
+ * owner that suite IS — and it is what `--suites owed` reads to decide which
+ * suites a push has to pay for. A stale root there owns nothing, silently, and
+ * the hole it leaves looks exactly like a clean diff: no suite owed, push green,
+ * the double that stands in for the changed tool never compared against it.
+ *
+ * So the claim is checked rather than trusted: the roots exist, the tests a
+ * suite runs live inside the source it answers for, and the mapping actually
+ * resolves — a file under a suite's own corpus must owe that suite.
+ *
+ * Run: node tools/check-suite-ownership.mjs
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GATES, owedSuites } from './gates.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HAS_EDITOR = existsSync(path.join(ROOT, 'desktop', 'package.json'));
+
+const findings = [];
+const suites = GATES.filter((g) => g.covers?.length);
+let roots = 0;
+let skipped = 0;
+
+for (const gate of suites) {
+ // A suite that answers for nothing can never be owed, so a push would never
+ // run it and nothing would say why. That is the shape this file exists for.
+ if (!gate.owns?.length) {
+ findings.push(`${gate.id} runs a suite but declares no \`owns\` — no change can ever owe it`);
+ continue;
+ }
+ for (const root of gate.owns) {
+ // The editor is an optional submodule; an absent checkout is not a stale root.
+ if (!HAS_EDITOR && root === 'desktop') { skipped++; continue; }
+ roots++;
+ if (!existsSync(path.join(ROOT, root))) {
+ findings.push(`${gate.id} owns "${root}", which is not in the tree — it owns nothing`);
+ }
+ }
+ for (const dir of gate.covers) {
+ if (!HAS_EDITOR && dir.startsWith('desktop/')) continue;
+ if (!gate.owns.some((r) => dir === r || dir.startsWith(`${r}/`))) {
+ findings.push(`${gate.id} runs ${dir}, which is outside everything it says it answers for `
+ + `(${gate.owns.join(', ')}) — one of the two has been moved`);
+ }
+ // The table is only worth having if it resolves. A file inside a suite's own
+ // corpus is the one path that must owe it.
+ const probe = `${dir}/probe.test.ts`;
+ if (!owedSuites([probe]).has(gate.id)) {
+ findings.push(`${gate.id} is not owed by ${probe}, a file in the corpus it runs — `
+ + 'the ownership lookup does not reach it');
+ }
+ }
+}
+
+if (findings.length === 0) {
+ console.log(`check-suite-ownership: ${suites.length} suite(s) answer for ${roots} source root(s)`
+ + `${skipped ? `, ${skipped} not checked without an editor checkout` : ''}; every corpus resolves.`);
+ process.exit(0);
+}
+for (const f of findings) console.error(` - ${f}`);
+console.error(`\ncheck-suite-ownership: ${findings.length} finding(s).`);
+process.exit(1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index fd2a36613..761164628 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -32,10 +32,10 @@ export const SCOPES = ['local', 'ci'];
* 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.
+ * `covers` is also the COST dimension: `--suites none` drops exactly the gates
+ * that run a suite — orthogonal to `where`, which says a gate CANNOT run here.
+ * `owns` is the other half: the SOURCE a suite answers for, and `--suites owed`
+ * runs the ones a change touched, so it meets its unit-test owner before the remote.
*/
export const GATES = [
{ id: 'tsc-sdk', run: 'pnpm --filter ./sdk exec tsc --noEmit' },
@@ -90,7 +90,7 @@ export const GATES = [
// this gate reported success having type-checked nothing at all.
{ id: 'tsc-editor', run: 'pnpm --filter @estella/editor exec tsc --noEmit', needs: 'editor' },
{ id: 'editor-tests', run: 'pnpm --filter @estella/editor test',
- needs: 'editor', covers: ['desktop/tests'] },
+ needs: 'editor', covers: ['desktop/tests'], owns: ['desktop'] },
// What type-checking cannot see: the renderer runs in a browser, so a module
// that reaches it with a node dependency throws before React mounts and takes
// the whole editor with it.
@@ -100,20 +100,23 @@ export const GATES = [
// could survive fails here rather than in someone else's project.
{ id: 'tsc-plugins', run: 'pnpm -r --filter "./plugins/*" exec tsc --noEmit' },
{ id: 'plugin-tests', run: 'pnpm -r --filter "./plugins/*" test',
- covers: ['plugins/audio-mixer/tests', 'plugins/ldtk/tests', 'plugins/minigame-services/tests'] },
+ covers: ['plugins/audio-mixer/tests', 'plugins/ldtk/tests', 'plugins/minigame-services/tests'],
+ owns: ['plugins'] },
// The engine's own TS suites (pipeline + tooling). They lived in desktop/tests
// until the editor split, where a checkout without the editor ran none of them.
- { id: 'engine-tests', run: 'pnpm run test', covers: ['pipeline/tests', 'tools/tests'] },
+ { id: 'engine-tests', run: 'pnpm run test', covers: ['pipeline/tests', 'tools/tests'],
+ owns: ['pipeline', 'tools'] },
// The SDK's own suites. They were run by NOTHING until 2026-08-30: the gate
// list said 76/76 while four of them did not compile against the source they
// test, and only a hand-run vitest found it.
- { id: 'sdk-tests', run: 'pnpm --filter ./sdk test', covers: ['sdk/tests'] },
+ { id: 'sdk-tests', run: 'pnpm --filter ./sdk test', covers: ['sdk/tests'], owns: ['sdk'] },
// The AOT compiler carries its own oracle: a real example system lowered to
// EIR must move a world exactly the way node moves it.
// It also compiles the emitted C and requires the same bytes back: natively
// with any C compiler, and as wasm where emsdk is unpacked. Without either it
// still passes and PRINTS that the differential did not run — read the log.
- { id: 'compiler-tests', run: 'pnpm --filter @estella/compiler test', covers: ['compiler/tests'] },
+ { id: 'compiler-tests', run: 'pnpm --filter @estella/compiler test', covers: ['compiler/tests'],
+ owns: ['compiler'] },
// The plugins we ship prove the public API only if they are held to it.
{ id: 'plugin-boundary', run: 'node tools/check-plugin-boundary.mjs' },
// Same shape of rule, other direction: what builds a project may not need the
@@ -148,6 +151,9 @@ export const GATES = [
{ id: 'project-settings', run: 'node tools/check-project-settings.mjs', needs: 'editor' },
// "The full gate suite is green" only means something if every suite is in it.
{ id: 'verification-authority', run: 'node tools/check-verification-authority.mjs' },
+ // ...and "this push ran the suites it owed" only means something if what each
+ // suite answers for is a claim that resolves.
+ { id: 'suite-ownership', run: 'node tools/check-suite-ownership.mjs' },
{ id: 'workflows', run: 'node tools/check-workflows.mjs' },
{ id: 'tool-spawn', run: 'node tools/check-tool-spawn.mjs' },
{ id: 'tool-calls', run: 'node tools/check-tool-calls.mjs', needs: 'editor' },
@@ -300,10 +306,33 @@ export const GATES = [
{ id: 'documents', run: 'node build-tools/cli.js validate-documents' },
];
-/** The gates a scope runs, in declaration order. `hasEditor` gates the editor ones. */
-export function gatesFor(scope, hasEditor = true, { suites = true } = {}) {
+/** Whether `p` names, or sits under, one of `roots`. */
+function under(p, roots) {
+ return roots.some((r) => p === r || p.startsWith(`${r}/`));
+}
+
+/**
+ * The suites `changed` owes — the direct unit-test owner of every path in it.
+ *
+ * A path no suite claims owes none: docs, examples and the C++ tree have owners
+ * of other kinds. Over-running is the safe direction here and under-running is
+ * the defect, so `owns` is declared at package granularity rather than per file.
+ */
+export function owedSuites(changed) {
+ const owed = new Set();
+ for (const g of GATES) {
+ if (g.owns && changed.some((p) => under(p, g.owns))) owed.add(g.id);
+ }
+ return owed;
+}
+
+/**
+ * The gates a scope runs, in declaration order. `hasEditor` gates the editor
+ * ones; `suites` is 'all', 'none', or the set of suite ids a diff owes.
+ */
+export function gatesFor(scope, hasEditor = true, { suites = 'all' } = {}) {
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')
- && (suites || !g.covers?.length));
+ && (!g.covers?.length || suites === 'all' || (suites !== 'none' && suites.has(g.id))));
}
diff --git a/tools/run-gates.mjs b/tools/run-gates.mjs
index 9279c9def..005e34093 100644
--- a/tools/run-gates.mjs
+++ b/tools/run-gates.mjs
@@ -9,12 +9,13 @@
*
* node tools/run-gates.mjs --scope local
* node tools/run-gates.mjs --scope ci
+ * node tools/run-gates.mjs --scope local --suites owed (the pre-push hook)
*/
-import { spawnSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
import { existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
-import { SCOPES, GATES, gatesFor } from './gates.mjs';
+import { SCOPES, GATES, gatesFor, owedSuites } from './gates.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const argv = process.argv.slice(2);
@@ -33,10 +34,45 @@ 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'));
-// --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');
+/**
+ * Which suite gates this caller pays for: `all` (default, and CI), `owed` (those
+ * whose `owns` this change touched — the pre-push hook), or `none`.
+ *
+ * @details A machine that cannot run an owed suite is not silently excused: it
+ * says what it needs and the push stops, per check-suite-preconditions.
+ */
+const SUITE_MODES = ['all', 'owed', 'none'];
+if (argv.includes('--no-suites')) {
+ console.error('run-gates: --no-suites is now --suites none (or --suites owed, which the'
+ + ' pre-push hook uses).');
+ process.exit(2);
+}
+const SUITE_MODE = flag('suites', 'all');
+if (!SUITE_MODES.includes(SUITE_MODE)) {
+ console.error(`run-gates: unknown --suites "${SUITE_MODE}" (have: ${SUITE_MODES.join(', ')})`);
+ process.exit(2);
+}
+
+/**
+ * What this push would ADD to the remote: COMMITTED work since the branch left
+ * it. Not the working tree — what is uncommitted is not going out, and on a
+ * checkout two lines of work share it would owe suites for someone else's
+ * half-finished edit and block this push on their red.
+ */
+function changedPaths() {
+ const git = (args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', maxBuffer: 1 << 28 });
+ let base = '';
+ for (const ref of ['origin/master', 'master']) {
+ try { base = git(['merge-base', 'HEAD', ref]).trim(); break; } catch { /* no such ref here */ }
+ }
+ // No remote to compare against is not "nothing changed": the last commit is
+ // the smallest honest answer, and it is what a fresh clone's first push has.
+ const out = git(base ? ['diff', '--name-only', base, 'HEAD'] : ['diff', '--name-only', 'HEAD~1', 'HEAD']);
+ return [...new Set(out.split('\n').map((l) => l.trim()).filter(Boolean))];
+}
+
+const changed = SUITE_MODE === 'owed' ? changedPaths() : [];
+const SUITES = SUITE_MODE === 'owed' ? owedSuites(changed) : SUITE_MODE;
/**
* Whether every DECLARED gate has to have run, not just every gate that could.
*
@@ -69,7 +105,8 @@ const declared = GAPS.filter((g) => process.env[g.env] === g.value);
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 unpaid = gatesFor(SCOPE, HAS_EDITOR)
+ .filter((g) => g.covers?.length && !gates.includes(g));
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) {
@@ -100,9 +137,18 @@ 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.
+ // The whole point of not paying for a suite is that it is CHEAP, not that it
+ // is quiet. Under `owed` the count of paths is part of the claim: "no suite was
+ // owed" means nothing unless it is attached to a diff that was actually read.
+ if (SUITE_MODE === 'owed') {
+ console.log(` ${changed.length} changed path(s) read for suite ownership`
+ + `${SUITES.size ? '' : ' — none of them under a suite\'s `owns`'}`);
+ }
if (unpaid.length) {
- console.log(` test suites NOT run: ${unpaid.map((g) => g.id).join(', ')} — --no-suites; CI runs them`);
+ const why = SUITE_MODE === 'owed'
+ ? 'nothing changed under what they answer for; CI runs them all'
+ : `--suites ${SUITE_MODE}; CI runs them`;
+ console.log(` test suites NOT run: ${unpaid.map((g) => g.id).join(', ')} — ${why}`);
}
}
diff --git a/tools/tests/suite-ownership.test.ts b/tools/tests/suite-ownership.test.ts
new file mode 100644
index 000000000..1740f4dc9
--- /dev/null
+++ b/tools/tests/suite-ownership.test.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file suite-ownership.test.ts — the lookup a push decides its suites by.
+ *
+ * The shape it exists for happened: a tool gained a call, the double that stands
+ * in for it in the editor suite did not, and the push boundary ran no suite that
+ * compares the two.
+ */
+import { describe, it, expect } from 'vitest';
+// @ts-expect-error — a repo tool, shipped as .mjs with no declarations
+import { GATES, owedSuites } from '../gates.mjs';
+
+const owed = (...paths: string[]): string[] => [...owedSuites(paths)].sort();
+
+describe('owedSuites names the direct unit-test owner of a change', () => {
+ it('owes the editor suite for the editor source, which is where it happened', () => {
+ expect(owed('desktop/src/tools/transformTools.ts')).toEqual(['editor-tests']);
+ // The editor is a submodule: a pointer bump names the directory itself,
+ // and so does a dirty checkout. Both are changes the suite answers for.
+ expect(owed('desktop')).toEqual(['editor-tests']);
+ });
+
+ it('owes each package suite for its own source', () => {
+ expect(owed('sdk/src/camera/Camera.ts')).toEqual(['sdk-tests']);
+ expect(owed('pipeline/src/world/cookWorld.ts')).toEqual(['engine-tests']);
+ expect(owed('tools/check-suite-ownership.mjs')).toEqual(['engine-tests']);
+ expect(owed('plugins/ldtk/src/index.ts')).toEqual(['plugin-tests']);
+ expect(owed('compiler/src/lower.ts')).toEqual(['compiler-tests']);
+ });
+
+ it('owes every suite a change actually touches, and only those', () => {
+ expect(owed('desktop/src/panels/Viewport.tsx', 'sdk/src/ui/util/math.ts'))
+ .toEqual(['editor-tests', 'sdk-tests']);
+ });
+
+ // Docs, examples and the C++ tree have owners of other kinds; claiming a TS
+ // unit suite for them would run minutes that answer nothing.
+ it('owes nothing for source no suite is the unit-test owner of', () => {
+ expect(owed('docs/REARCH_NOTES.md', 'examples/sprite-rendering/src/main.ts',
+ 'native/src/app.cpp', 'README.md')).toEqual([]);
+ });
+
+ // A prefix must not swallow a sibling that merely starts with the same letters.
+ it('matches on path segments, not on string prefixes', () => {
+ expect(owed('sdk-extras/src/x.ts')).toEqual([]);
+ expect(owed('toolsmith/x.mjs')).toEqual([]);
+ });
+
+ // The declaration this all reads from cannot be half-filled: a suite with no
+ // `owns` is never owed by anything and nothing says so.
+ it('leaves no suite unable to be owed', () => {
+ const orphans = (GATES as Array<{ id: string; covers?: string[]; owns?: string[] }>)
+ .filter((g) => g.covers?.length && !g.owns?.length)
+ .map((g) => g.id);
+ expect(orphans).toEqual([]);
+ });
+});