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 checker nobody runs is a checker that rots

esengine2d4663273747
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8360e73b2..a166fe8c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -74,6 +74,31 @@ published separately; it ships inside the editor.
and the software rasterizer agree on all four to the byte.
+- **`check-verifier-owners` — a checker nobody runs is a checker that rots.**
+ `check-release-gate` holds one direction: every exit criterion has something
+ answering it. Nothing held the other, and `verify:aot` fell through it — a
+ verifier with no workflow, no gate, no criterion and no script calling it,
+ failing against a package shape that had changed under it.
+
+ So every `tools/check-*.mjs` and `tools/verify-*.mjs` owes a caller: a
+ workflow, the gate list, a package script, another tool that spawns it, or an
+ exit criterion saying who runs it and why a machine cannot. Prose does not
+ count — a tool named only in a comment is exactly the case. 60 checkers, one
+ orphan, now owned. Sabotage-verified both ways: a new unowned checker turns it
+ red, and so does taking an existing one out of the gate list.
+
+ It refuses to shrink its own corpus in silence, too: `git ls-files` names files
+ a checkout may not have — a submodule, a deletion not yet committed — and those
+ are reported rather than skipped past.
+
+- **A crash on a device is an exit criterion, and asking for it can no longer
+ answer "skipped".** `verify-bootlog-crash` builds the real handler for arm64,
+ pushes it, faults on purpose and reads the record back — the claim that a game
+ dying on someone else's phone leaves something they can send. It was the one
+ orphan above. It still skips on a laptop with no phone, which is right, and
+ `--require-device` turns that into a failure, which is what a release asking
+ the question came for.
+
- **An exported WEB game is checked for running its systems compiled, and the
checker that was supposed to do it had rotted.** `verify:aot` exports
`examples/ecs-basics` through the CLI, boots the package and asks the host how
diff --git a/tools/check-verifier-owners.mjs b/tools/check-verifier-owners.mjs
new file mode 100644
index 000000000..7297c0a39
--- /dev/null
+++ b/tools/check-verifier-owners.mjs
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-verifier-owners — every checker in tools/ is run by something.
+ *
+ * A verifier nobody runs does not sit still: it rots against the thing it
+ * checks and says nothing, because saying something requires being run.
+ * `verify:aot` spent two releases failing on `systems.json`, a file the export
+ * stopped writing the day the manifest moved inline — and the web road's only
+ * "is it actually dispatched" check was gone that whole time.
+ *
+ * So a checker owes an owner: a workflow, the gate list, an exit criterion, a
+ * package script, or another tool that spawns it. Where a machine genuinely
+ * cannot run one — a phone in your hand — the owner is a criterion saying who
+ * does and why, which is a declaration and not a silence.
+ *
+ * node tools/check-verifier-owners.mjs
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SELF = 'tools/check-verifier-owners.mjs';
+
+const read = (rel) => (existsSync(path.join(ROOT, rel)) ? readFileSync(path.join(ROOT, rel), 'utf8') : '');
+const tracked = (glob) => execFileSync('git', ['ls-files', glob], { cwd: ROOT, encoding: 'utf8' })
+ .split('\n').filter(Boolean);
+
+/** Where an owner may be declared. A name here is a claim that something runs it. */
+const DECLARATIONS = [
+ ...readdirSync(path.join(ROOT, '.github', 'workflows'))
+ .filter((f) => /\.ya?ml$/.test(f)).map((f) => `.github/workflows/${f}`),
+ 'tools/gates.mjs', 'tools/releaseGate.mjs',
+ 'package.json', 'sdk/package.json', 'pipeline/package.json', 'desktop/package.json',
+].map(read).join('\n');
+
+/**
+ * The rest of the tooling, with comments stripped: a tool named only in prose is
+ * a tool nothing runs, and that is the case this exists to find. Quoted or
+ * interpolated is the shape of a spawn, an import or an argv.
+ */
+const absent = [];
+function code(rel) {
+ // git names files this checkout does not have: a deletion not yet committed,
+ // an unchecked-out submodule. Shrinking the corpus in silence is how a
+ // scanner reports green on a smaller world, so they are counted and said.
+ const abs = path.join(ROOT, rel);
+ if (!existsSync(abs)) { absent.push(rel); return ''; }
+ return readFileSync(abs, 'utf8')
+ .replace(/\/\*[\s\S]*?\*\//g, ' ')
+ .split('\n').map((l) => l.replace(/(^|[^:'"`\w])\/\/.*$/, '$1')).join('\n');
+}
+
+const CHECKERS = tracked('tools/*.mjs').filter((f) => /\/(check|verify)-[\w-]+\.mjs$/.test(f));
+const CALLERS = [...tracked('tools/*.mjs'), ...tracked('tools/**/*.mjs'), ...tracked('build-tools/**/*.js')]
+ .filter((f) => f !== SELF);
+const callerCode = CALLERS.map(code).join('\n');
+
+const orphans = [];
+for (const rel of CHECKERS) {
+ if (rel === SELF) continue;
+ if (absent.includes(rel)) continue;
+ const base = path.basename(rel);
+ if (DECLARATIONS.includes(base)) continue;
+ // Named by another tool in CODE — a spawn, an import, an argv — not in prose.
+ // Its own file is in the corpus, so a self-mention has to be discounted.
+ const mine = code(rel).split(base).length - 1;
+ if (callerCode.split(base).length - 1 > mine) continue;
+ orphans.push(rel);
+}
+
+if (orphans.length) {
+ console.error('check-verifier-owners: nothing runs these, so nothing will notice when they rot.\n');
+ for (const o of orphans) console.error(` ${o}`);
+ console.error('\nGive each a caller — a workflow, tools/gates.mjs, a package script — or an exit'
+ + ' criterion in tools/releaseGate.mjs saying who runs it and why a machine cannot.');
+ process.exit(1);
+}
+if (absent.length) {
+ console.log(`check-verifier-owners: ${absent.length} tracked file(s) are not in this checkout`
+ + ` and were not read: ${absent.slice(0, 5).join(', ')}${absent.length > 5 ? ' …' : ''}`);
+}
+console.log(`check-verifier-owners: ${CHECKERS.length - absent.length} checkers, every one of them`
+ + ' run by something.');
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 938ca5e84..0cd7eeac4 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -163,6 +163,10 @@ export const GATES = [
{ id: 'engine-gaps', run: 'node tools/check-engine-gaps.mjs' },
{ id: 'minigame-host', run: 'node tools/check-minigame-host.mjs' },
{ id: 'release-gate', run: 'node tools/check-release-gate.mjs' },
+ // release-gate says every criterion has something answering it; this says the
+ // other direction — every checker has something RUNNING it. `verify:aot` spent
+ // two releases broken because nothing did.
+ { id: 'verifier-owners', run: 'node tools/check-verifier-owners.mjs' },
{ id: 'component-reference', run: 'node tools/component-reference.mjs --check' },
{ id: 'api-stability-page', run: 'node tools/api-stability.mjs --check' },
// The per-symbol tiers say what is frozen; this says what a creator can build
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index 20126f197..bdd007068 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -178,6 +178,14 @@ export const CRITERIA = [
answeredBy: 'node tools/verify-aot-parity.mjs',
needs: ['tools/verify-aot-parity.mjs', 'examples/space-shooter/src/systems/effects.ts'],
},
+ {
+ id: 'a-crash-leaves-something-the-player-can-send',
+ says: 'the boot record survives a crash on a real device, with the phase and a backtrace',
+ // `--require-device` on purpose: without it the tool skips where there is no
+ // phone, which is right on a laptop and is a false pass under a release.
+ answeredBy: 'node tools/verify-bootlog-crash.mjs --require-device',
+ needs: ['tools/verify-bootlog-crash.mjs', 'native/host/BootLog.cpp'],
+ },
{
id: 'old-projects-open',
says: 'projects released by older versions still open, with nothing dropped',
diff --git a/tools/verify-bootlog-crash.mjs b/tools/verify-bootlog-crash.mjs
index 563111488..ad871f34a 100644
--- a/tools/verify-bootlog-crash.mjs
+++ b/tools/verify-bootlog-crash.mjs
@@ -58,17 +58,25 @@ function device(adb) {
}
}
-const adb = adbPath();
-const clang = ndkClang();
-if (!clang) {
- console.log('verify-bootlog-crash: SKIP — no Android NDK found');
- process.exit(0);
-}
-if (!device(adb)) {
- console.log('verify-bootlog-crash: SKIP — no adb device attached');
+// Skipping is right on a laptop with no phone and wrong when a release is being
+// cut against this, so the caller says which it is. Exit 0 either way would make
+// "there was no device" indistinguishable from "the record survived the crash".
+const REQUIRE_DEVICE = process.argv.includes('--require-device');
+function unavailable(why) {
+ if (REQUIRE_DEVICE) {
+ console.error(`verify-bootlog-crash: CANNOT RUN — ${why}. This was asked for with`
+ + ' --require-device, so it is a failure and not a pass.');
+ process.exit(1);
+ }
+ console.log(`verify-bootlog-crash: SKIP — ${why}`);
process.exit(0);
}
+const adb = adbPath();
+const clang = ndkClang();
+if (!clang) unavailable('no Android NDK found');
+if (!device(adb)) unavailable('no adb device attached');
+
mkdirSync(OUT, { recursive: true });
const bin = path.join(OUT, 'bootlog_crash_test');
console.log('building the record + handler for arm64…');