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): the gate list can be surveyed, and not only gated on

esengine740e16f9ca66
diff --git a/tools/run-gates.mjs b/tools/run-gates.mjs
index 005e34093..3ba686ef6 100644
--- a/tools/run-gates.mjs
+++ b/tools/run-gates.mjs
@@ -7,12 +7,20 @@
* reading a build an earlier one failed to produce reports a second, invented
* problem on top of the real one.
*
+ * That is right for a gate and wrong for a SURVEY. One red hides the hundred
+ * gates behind it, so "fix it and re-run" discovers the next red one at a time
+ * and a release never learns how many it has. `--keep-going` runs the whole list
+ * and prints the matrix — a scan, not a verdict: every red after the first is
+ * marked `after-red`, because it may be the invented problem the ordering exists
+ * to prevent, and only re-running it on a green tree settles which.
+ *
* 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)
+ * node tools/run-gates.mjs --scope local --keep-going --matrix out.json
*/
import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { SCOPES, GATES, gatesFor, owedSuites } from './gates.mjs';
@@ -82,6 +90,22 @@ const SUITES = SUITE_MODE === 'owed' ? owedSuites(changed) : SUITE_MODE;
*/
const COMPLETE = argv.includes('--complete');
+/**
+ * Survey the whole list instead of gating on it. A gate run answers "may this
+ * push go out"; a scan answers "how many reds does this release have", and the
+ * second question cannot be answered one re-run at a time.
+ */
+const SCAN = argv.includes('--keep-going');
+/** Where to write the matrix, for a reader that is not a terminal. */
+const MATRIX = (() => {
+ const i = argv.indexOf('--matrix');
+ return i >= 0 ? argv[i + 1] : null;
+})();
+if (MATRIX && !SCAN) {
+ console.error('run-gates: --matrix only has something to write under --keep-going.');
+ process.exit(2);
+}
+
/**
* What a caller has DECLARED this run cannot cover. Declaring is the honest way
* to run without a capability — the suite refuses to start otherwise — but it is
@@ -102,11 +126,40 @@ const GAPS = [
},
];
const declared = GAPS.filter((g) => process.env[g.env] === g.value);
-const gates = gatesFor(SCOPE, HAS_EDITOR, { suites: SUITES });
+/**
+ * Narrow to named gates. A scan finds ten reds at once and then each fix wants
+ * ONE of them re-run; without this the only way to re-check a gate is to pay for
+ * the hundred in front of it, which is how a fix goes unverified.
+ */
+const ONLY = (() => {
+ const i = argv.indexOf('--only');
+ return i >= 0 && argv[i + 1] ? argv[i + 1].split(',').map((x) => x.trim()).filter(Boolean) : null;
+})();
+const gates = gatesFor(SCOPE, HAS_EDITOR, { suites: SUITES })
+ .filter((g) => !ONLY || ONLY.includes(g.id));
+if (ONLY) {
+ // "Complete" is a claim about the whole declared list; a narrowed run cannot
+ // make it, and letting it try is how 69/69 got read as an answer about 80.
+ if (COMPLETE) {
+ console.error('run-gates: --only cannot be --complete — a narrowed run answers for the gates it named.');
+ process.exit(2);
+ }
+ const missing = ONLY.filter((id) => !gates.some((g) => g.id === id));
+ // A typo'd id silently running nothing is a green run that answered nothing —
+ // the exact shape every gate in this repo exists to refuse.
+ if (missing.length) {
+ console.error(`run-gates: --only named ${missing.length} gate(s) this scope does not run:`
+ + ` ${missing.join(', ')}`);
+ process.exit(2);
+ }
+}
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));
+/** Everything --only left out, suites included: a narrowed run answers for the
+ * gates it named and nothing else, and must not read as a list that went green. */
+const narrowed = ONLY ? gatesFor(SCOPE, HAS_EDITOR).filter((g) => !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) {
@@ -144,29 +197,91 @@ function reportSuites() {
console.log(` ${changed.length} changed path(s) read for suite ownership`
+ `${SUITES.size ? '' : ' — none of them under a suite\'s `owns`'}`);
}
- if (unpaid.length) {
+ if (unpaid.length && !ONLY) {
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}`);
}
+ if (narrowed.length) {
+ console.log(` --only: ${narrowed.length} gate(s) in this scope were NOT run, so this says`
+ + ' nothing about 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 = [];
+/**
+ * The line a reader wants out of a red gate's output. Gates print their own
+ * verdict in their own shape, so this is a net over the shapes they use rather
+ * than a parser for one — and the whole output is kept beside it, because a
+ * guess at the interesting line is not a substitute for the log.
+ */
+const ASSERTION = /(^|\s)(✗|FAIL|FAILED|error|Error:|AssertionError|error TS\d+|✘|×)/;
+function firstFailingLine(text) {
+ for (const line of text.split('\n')) {
+ const t = line.trim();
+ if (t && ASSERTION.test(t)) return t.slice(0, 300);
+ }
+ // Some gates say nothing and just exit non-zero; the last thing they said is
+ // still more use than an empty cell.
+ const said = text.split('\n').map((l) => l.trim()).filter(Boolean);
+ return said.length ? said[said.length - 1].slice(0, 300) : '(no output)';
+}
+
+/** What each gate answered, in scan mode. Ordered as the list is. */
+const matrix = [];
+let firstRed = null;
+
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 });
+ if (SCAN) process.stdout.write(`\n=== ${gate.id}\n ${gate.run}\n`);
+ // A scan keeps the output so the matrix can carry the failing line; a gate run
+ // streams it, because a person is watching one command and wants it live.
+ const r = SCAN
+ ? spawnSync('sh', ['-c', gate.run], {
+ cwd: ROOT, encoding: 'utf8', maxBuffer: 1 << 28,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ })
+ : spawnSync('sh', ['-c', gate.run], { cwd: ROOT, stdio: 'inherit' });
+ const ms = Date.now() - began;
+ spent.push({ id: gate.id, ms });
// 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) {
+ if (r.error && !SCAN) {
console.error(`\n✗ could not run the gates: ${r.error.message}`);
console.error(' they are shell commands — run this from a shell that has `sh` on PATH.');
process.exit(2);
}
+ if (SCAN) {
+ const out = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+ process.stdout.write(out);
+ const status = r.error ? 'would-not-start'
+ // Exit 2 is "this machine could not answer it", which is a hole and not a
+ // verdict — counted apart, per check-unanswered-exits, so a scan does not
+ // report a missing toolchain as a broken subject.
+ : r.status === 2 ? 'unanswered'
+ : r.status === 0 ? 'pass' : 'fail';
+ if (status !== 'pass' && !firstRed) firstRed = gate.id;
+ matrix.push({
+ id: gate.id,
+ run: gate.run,
+ status,
+ exit: r.error ? null : r.status,
+ secs: +(ms / 1000).toFixed(1),
+ suite: !!gate.covers?.length,
+ // Ordering is load-bearing here, so a red behind another red is a
+ // candidate for the invented problem the short-circuit exists to avoid.
+ afterRed: status !== 'pass' && firstRed !== gate.id,
+ firstFailingLine: status === 'pass' ? null
+ : r.error ? r.error.message : firstFailingLine(out),
+ });
+ console.log(status === 'pass' ? `✓ ${gate.id} (${(ms / 1000).toFixed(0)}s)`
+ : `✗ ${gate.id} — ${status} (${(ms / 1000).toFixed(0)}s)`);
+ continue;
+ }
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
@@ -177,6 +292,39 @@ for (const gate of gates) {
}
}
+if (SCAN) {
+ const red = matrix.filter((m) => m.status !== 'pass');
+ console.log(`\ngates ${SCOPE} SCAN: ${matrix.length - red.length}/${matrix.length} green`
+ + ` in ${(spent.reduce((t, g) => t + g.ms, 0) / 1000).toFixed(0)}s`);
+ for (const m of red) {
+ console.log(` ✗ ${m.id} — ${m.status}${m.exit === null ? '' : ` (exit ${m.exit})`}`
+ + `${m.afterRed ? ' [after-red: may be downstream]' : ''}`);
+ console.log(` ${m.firstFailingLine}`);
+ }
+ if (noEditor.length) {
+ console.log(` ${noEditor.length} editor gate(s) had no checkout: ${noEditor.map((g) => g.id).join(', ')}`);
+ }
+ reportSuites();
+ for (const g of skipped) console.log(` not in this scope: ${g.id} — ${g.why}`);
+ // A scan is not a verdict, and saying so is the whole reason it is a separate
+ // mode: reds after the first may be the ordering's invented problem.
+ if (red.some((m) => m.afterRed)) {
+ console.log('\n reds marked [after-red] ran on a tree an earlier gate said was broken —'
+ + ' re-run them once the earlier ones are green before believing them.');
+ }
+ if (MATRIX) {
+ writeFileSync(MATRIX, `${JSON.stringify({
+ scope: SCOPE, host: process.platform, at: new Date().toISOString(),
+ declared: GATES.length, ran: matrix.length,
+ noEditor: noEditor.map((g) => g.id),
+ notInScope: skipped.map((g) => g.id),
+ gates: matrix,
+ }, null, 2)}\n`);
+ console.log(` matrix written to ${MATRIX}`);
+ }
+ process.exit(red.length ? 1 : 0);
+}
+
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)` : ''));