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): --suites related runs of an owed suite only the tests that reach what changed - where its runner can follow imports from every changed file, and the whole suite where it cannot; the run names each suite it ran in part
yhh7152728f5956
diff --git a/tools/gates.mjs b/tools/gates.mjsindex 6ac731fe8..9d072ac29 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -34,6 +34,8 @@ export const SCOPES = ['local', 'ci'];* 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.+ * `related` is how a suite runs IN PART: `root`, the package its runner takes paths from, and `run`, the command the changed files are+ * handed to, which runs the tests that reach them (`--suites related`, see relatedRun). A suite without one is run whole.*/export const GATES = [// `exclusive: true` is a build or a writer of what a later gate reads: a `--jobs` run cuts the list there and runs it alone.@@ -113,11 +115,13 @@ export const GATES = [// 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'],- owns: ['pipeline', 'tools'] },+ owns: ['pipeline', 'tools'],+ related: { root: '.', run: 'pnpm exec vitest related --run --config vitest.engine.config.ts' } },// 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'], owns: ['sdk'] },+ { id: 'sdk-tests', run: 'pnpm --filter ./sdk test', covers: ['sdk/tests'], owns: ['sdk'],+ related: { root: 'sdk', run: 'pnpm --filter ./sdk exec vitest related --run' } },// 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@@ -425,6 +429,31 @@ export function owedSuites(changed) {return owed;}+/** The most changed files a suite is run in part for: past it the whole suite is the cheaper answer and the surer one. */+export const RELATED_MOST = 80;++/**+ * How `gate` runs in part for `changed`: the command that runs only the tests that reach what changed under it, and how many files+ * that is. Null where the whole suite is owed instead, which is every case this cannot answer for: a suite with no `related`, a change+ * that is not TypeScript source its runner can follow (a config, a fixture, a generated binary: anything may read those), a file that+ * is gone (what imported it is not named by its path any more), or more files than RELATED_MOST.+ *+ * @details A runner follows imports, so a test that reads a changed file some other way (a path it builds, a file it opens) is missed.+ * That is why this is a mode a caller asks for by name and the run says so, and why CI runs every suite whole.+ */+export function relatedRun(gate, changed, exists = () => true) {+ if (!gate.related || !gate.owns) return null;+ const mine = changed.filter((p) => under(p, gate.owns));+ if (mine.length === 0 || mine.length > RELATED_MOST) return null;+ const root = gate.related.root === '.' ? '' : `${gate.related.root}/`;+ const files = [];+ for (const p of mine) {+ if (!/\.(ts|tsx|mts)$/.test(p) || /(^|\/)[^/]*\.config\.[a-z]+$/.test(p) || !p.startsWith(root) || !exists(p)) return null;+ files.push(p.slice(root.length));+ }+ return { run: `${gate.related.run} ${files.map((f) => `"${f}"`).join(' ')}`, files: files.length };+}+/*** 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.diff --git a/tools/run-gates.mjs b/tools/run-gates.mjsindex f895bec56..efe07256a 100644--- a/tools/run-gates.mjs+++ b/tools/run-gates.mjs@@ -17,6 +17,7 @@* node tools/run-gates.mjs --scope local* node tools/run-gates.mjs --scope ci* node tools/run-gates.mjs --scope local --suites owed+ * node tools/run-gates.mjs --scope local --suites related* node tools/run-gates.mjs --scope local --where local* node tools/run-gates.mjs --scope local --keep-going --matrix out.json*/@@ -24,7 +25,7 @@ import { execFileSync, spawn, spawnSync } from 'node:child_process';import { existsSync, writeFileSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { SCOPES, GATES, gatesFor, owedSuites } from './gates.mjs';+import { SCOPES, GATES, gatesFor, owedSuites, relatedRun } from './gates.mjs';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');const argv = process.argv.slice(2);@@ -45,12 +46,13 @@ if (!SCOPES.includes(SCOPE)) {const HAS_EDITOR = existsSync(path.join(ROOT, 'desktop', 'package.json'));/*** Which suite gates this caller pays for: `all` (default, and CI), `owed` (those- * whose `owns` this change touched), or `none`.+ * whose `owns` this change touched), `related` (those, and of each only the tests+ * that reach what changed, where its runner can say which), or `none`.** @details A machine that cannot run an owed suite is not silently excused: it* says what it needs and the run stops, per check-suite-preconditions.*/-const SUITE_MODES = ['all', 'owed', 'none'];+const SUITE_MODES = ['all', 'owed', 'related', 'none'];if (argv.includes('--no-suites')) {console.error('run-gates: --no-suites is now --suites none (or --suites owed).');process.exit(2);@@ -79,8 +81,9 @@ function changedPaths() {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;+const BY_CHANGE = SUITE_MODE === 'owed' || SUITE_MODE === 'related';+const changed = BY_CHANGE ? changedPaths() : [];+const SUITES = BY_CHANGE ? owedSuites(changed) : SUITE_MODE;/*** Whether every DECLARED gate has to have run, not just every gate that could.*@@ -96,6 +99,10 @@ const COMPLETE = argv.includes('--complete');* second question cannot be answered one re-run at a time.*/const SCAN = argv.includes('--keep-going');+if (COMPLETE && SUITE_MODE === 'related') {+ console.error('run-gates: --suites related cannot be --complete — a suite run in part answers for the tests it ran.');+ process.exit(2);+}/** Where to write the matrix, for a reader that is not a terminal. */const MATRIX = (() => {const i = argv.indexOf('--matrix');@@ -155,8 +162,16 @@ if (WHERE && !SCOPES.includes(WHERE)) {console.error(`run-gates: unknown --where "${WHERE}" (have: ${SCOPES.join(', ')})`);process.exit(2);}+/** The suites run in part, and for how many changed files each: a green from one of them is about those tests only. */+const inPart = new Map();const gates = gatesFor(SCOPE, HAS_EDITOR, { suites: SUITES })- .filter((g) => (!ONLY || ONLY.includes(g.id)) && (!WHERE || g.where === WHERE));+ .filter((g) => (!ONLY || ONLY.includes(g.id)) && (!WHERE || g.where === WHERE))+ .map((g) => {+ const part = SUITE_MODE === 'related' ? relatedRun(g, changed, (p) => existsSync(path.join(ROOT, p))) : null;+ if (!part) return g;+ inPart.set(g.id, part.files);+ return { ...g, run: part.run };+ });/** Either form answers for the gates it selected and for nothing else. */const NARROWED = Boolean(ONLY || WHERE);if (NARROWED) {@@ -182,10 +197,10 @@ if (NARROWED) {const skipped = GATES.filter((g) => g.where && g.where !== SCOPE);/** Suites this run is not paying for — named, never silently absent. */const unpaid = gatesFor(SCOPE, HAS_EDITOR)- .filter((g) => g.covers?.length && !gates.includes(g));+ .filter((g) => g.covers?.length && !gates.some((ran) => ran.id === g.id));/** Everything a narrowing left out, suites included: such a run answers for the* gates it selected and nothing else, and must not read as a list that went green. */-const narrowed = NARROWED ? gatesFor(SCOPE, HAS_EDITOR).filter((g) => !gates.includes(g)) : [];+const narrowed = NARROWED ? gatesFor(SCOPE, HAS_EDITOR).filter((g) => !gates.some((ran) => ran.id === g.id)) : [];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) {@@ -208,7 +223,11 @@ if (argv.includes('--plan')) {*/function reportSuites() {const suites = gates.filter((g) => g.covers?.length);- if (suites.length) console.log(` test suites run: ${suites.map((g) => g.id).join(', ')}`);+ const whole = suites.filter((g) => !inPart.has(g.id));+ if (whole.length) console.log(` test suites run: ${whole.map((g) => g.id).join(', ')}`);+ for (const [id, files] of inPart) {+ console.log(` test suite run IN PART: ${id} — only the tests that reach the ${files} changed file(s) under it; CI runs it whole`);+ }// A declared profile narrows what a suite covered, and the summary is where// that has to be said — otherwise "green" quietly means "green minus 300".for (const g of declared) console.log(` ${g.env}=${g.value} — ${g.says}`);@@ -219,12 +238,12 @@ function reportSuites() {// 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') {+ if (BY_CHANGE) {console.log(` ${changed.length} changed path(s) read for suite ownership`+ `${SUITES.size ? '' : ' — none of them under a suite\'s `owns`'}`);}if (unpaid.length && !NARROWED) {- const why = SUITE_MODE === 'owed'+ const why = BY_CHANGE? '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.tsindex 1740f4dc9..2552b6752 100644--- a/tools/tests/suite-ownership.test.ts+++ b/tools/tests/suite-ownership.test.ts@@ -9,7 +9,7 @@*/import { describe, it, expect } from 'vitest';// @ts-expect-error — a repo tool, shipped as .mjs with no declarations-import { GATES, owedSuites } from '../gates.mjs';+import { GATES, owedSuites, relatedRun, RELATED_MOST } from '../gates.mjs';const owed = (...paths: string[]): string[] => [...owedSuites(paths)].sort();@@ -56,3 +56,32 @@ describe('owedSuites names the direct unit-test owner of a change', () => {expect(orphans).toEqual([]);});});++describe('relatedRun runs a suite in part only where its runner can say which part', () => {+ const gate = (id: string) => (GATES as { id: string }[]).find((g) => g.id === id)!;++ it('hands the changed sources, by the paths of its package, to the runner that follows imports', () => {+ const part = relatedRun(gate('sdk-tests'), ['sdk/src/foliage/builder.ts', 'sdk/tests/foliage-builder.test.ts', 'docs/x.md']);+ expect(part.files).toBe(2);+ expect(part.run).toBe('pnpm --filter ./sdk exec vitest related --run "src/foliage/builder.ts" "tests/foliage-builder.test.ts"');+ expect(relatedRun(gate('engine-tests'), ['pipeline/src/world/cookWorld.ts']).run)+ .toBe('pnpm exec vitest related --run --config vitest.engine.config.ts "pipeline/src/world/cookWorld.ts"');+ });++ it('owes the whole suite for what no import names: a config, a fixture, a script, a file that is gone', () => {+ const sdk = gate('sdk-tests');+ expect(relatedRun(sdk, ['sdk/package.json'])).toBeNull();+ expect(relatedRun(sdk, ['sdk/vitest.config.ts'])).toBeNull();+ expect(relatedRun(sdk, ['sdk/src/a.ts', 'sdk/tests/fixtures/scene.json'])).toBeNull();+ expect(relatedRun(gate('engine-tests'), ['tools/gates.mjs'])).toBeNull();+ expect(relatedRun(sdk, ['sdk/src/gone.ts'], () => false)).toBeNull();+ });++ it('owes the whole suite past the most files, for a suite with no runner of the kind, and nothing where nothing changed under it', () => {+ const many = Array.from({ length: RELATED_MOST + 1 }, (_, i) => `sdk/src/f${i}.ts`);+ expect(relatedRun(gate('sdk-tests'), many)).toBeNull();+ expect(relatedRun(gate('sdk-tests'), many.slice(1)).files).toBe(RELATED_MOST);+ expect(relatedRun(gate('editor-tests'), ['desktop/src/a.ts'])).toBeNull();+ expect(relatedRun(gate('sdk-tests'), ['pipeline/src/a.ts'])).toBeNull();+ });+});