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): a push runs the suites its own change owes
esenginec75f4de51148
diff --git a/.githooks/pre-push b/.githooks/pre-pushindex 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; thenecho ''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 1fidiff --git a/package.json b/package.jsonindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.tsnew file mode 100644index 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([]);+ });+});