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.

fix(gates): a suite with no compiler says so, and --complete counts it

esengine5aed213c93f0
diff --git a/compiler/src/hostCC.ts b/compiler/src/hostCC.ts
index bf421fadf..dd7bfefa9 100644
--- a/compiler/src/hostCC.ts
+++ b/compiler/src/hostCC.ts
@@ -63,3 +63,27 @@ export function findHostCC(): string | null {
}
return null;
}
+
+/** How a checkout with no compiler says so, rather than skipping in silence. */
+export const NO_HOST_CC = 'ESTELLA_NO_HOST_CC';
+
+/**
+ * Prove the machine can compile before a suite claims to have compared
+ * anything. The differentials are the only thing holding the C half of the ABI
+ * to the TypeScript, so a run either has a compiler or declares that it has
+ * none — a skip nobody declared reads exactly like a test that ran.
+ */
+export function proveHostCC(suite: string): void {
+ if (findHostCC()) return;
+ if (process.env[NO_HOST_CC] === '1') {
+ console.warn(`\n[${suite}] ${NO_HOST_CC}=1 — nothing that needs a C compiler ran.\n`
+ + ' This run does not compare the emitted C against the interpreter,\n'
+ + ' and does not compile the ABI struct checks.\n');
+ return;
+ }
+ throw new Error(
+ 'no C compiler on PATH (tried clang, gcc, cc).\n'
+ + ' The differentials need one, and skipping them would report a partial run as a\n'
+ + ` clean one. Install one, or declare the gap with ${NO_HOST_CC}=1 — which the\n`
+ + ' gate runner then counts as something this machine could not answer.');
+}
diff --git a/compiler/tests/codegen.test.ts b/compiler/tests/codegen.test.ts
index d65b4f7c5..c48c237cb 100644
--- a/compiler/tests/codegen.test.ts
+++ b/compiler/tests/codegen.test.ts
@@ -319,18 +319,10 @@ const same = (a: AbiMemory, b: AbiMemory): boolean =>
// =============================================================================
-describe('the emitted C says what the interpreter says', () => {
- it('reports whether this gate could run at all', () => {
- // Not a skip: a missing compiler means the differential did not happen,
- // and a suite that stays silent about that is reporting a green it did
- // not earn.
- if (CC) console.log(`[codegen] the differential ran against ${CC}`);
- else console.warn('[codegen] NO C COMPILER ON PATH — the differential did NOT run.');
- expect(true).toBe(true);
- });
-
- if (!CC) return;
-
+// Skipped, never RETURNED from: an early return left these thirteen tests
+// unregistered, so a machine with no compiler reported a smaller suite passing
+// rather than a suite it could not run. globalSetup owns the announcement.
+describe.skipIf(!CC)('the emitted C says what the interpreter says', () => {
const tmp = mkdtempSync(join(tmpdir(), 'estella-aot-'));
it('MoveSystem: the whole image agrees with the interpreter, and both with node', () => {
diff --git a/compiler/tests/exact-trig.test.ts b/compiler/tests/exact-trig.test.ts
index 5a6b21343..ff0af079a 100644
--- a/compiler/tests/exact-trig.test.ts
+++ b/compiler/tests/exact-trig.test.ts
@@ -54,10 +54,6 @@ function bitsOf(x: number): string {
}
describe('the engine\'s trigonometry, on both sides of the compiler', () => {
- it('reports whether this gate could run at all', () => {
- if (!CC) console.warn('[exact-trig] NO C COMPILER — the comparison did NOT run.');
- });
-
it.skipIf(!CC)('answers the same bits in C as in TypeScript', () => {
const dir = mkdtempSync(join(tmpdir(), 'estella-trig-'));
mkdirSync(dir, { recursive: true });
diff --git a/compiler/tests/globalSetup.ts b/compiler/tests/globalSetup.ts
new file mode 100644
index 000000000..568f7a007
--- /dev/null
+++ b/compiler/tests/globalSetup.ts
@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file globalSetup.ts — a compiler has to be REACHABLE before a run claims
+ * to have compared the emitted C against the interpreter.
+ *
+ * @details The prerequisite belongs to one place, not to each `skipIf` that
+ * needs it: proved once here, a skip inside means what it says.
+ */
+import { proveHostCC } from '../src/hostCC';
+
+export default async function setup(): Promise<void> {
+ proveHostCC('compiler-tests');
+}
diff --git a/compiler/tests/native-module.test.ts b/compiler/tests/native-module.test.ts
index f5462867d..a177629cb 100644
--- a/compiler/tests/native-module.test.ts
+++ b/compiler/tests/native-module.test.ts
@@ -46,8 +46,7 @@ const lowered = lowerProgram(SOURCES, builtinShapes());
const move = lowered.module.systems.find((s) => s.name === 'MoveSystem');
describe('the compiled systems, as a module a native host loads', () => {
- it('reports whether this gate could run at all', () => {
- if (!CC) console.warn('[native-module] NO HOST C COMPILER — the build did NOT run.');
+ it('lowers the system the module is built from', () => {
expect(move, 'MoveSystem never lowered').toBeDefined();
expect(verifySystem(move!, lowered.module.comps, lowered.module.fns)).toEqual([]);
});
diff --git a/compiler/vitest.config.ts b/compiler/vitest.config.ts
index 863ac8f29..eed5d8b9b 100644
--- a/compiler/vitest.config.ts
+++ b/compiler/vitest.config.ts
@@ -2,7 +2,13 @@ import { defineConfig } from 'vitest/config';
import { fileURLToPath } from 'node:url';
export default defineConfig({
- test: { include: ['tests/**/*.test.ts'], environment: 'node' },
+ test: {
+ include: ['tests/**/*.test.ts'],
+ environment: 'node',
+ // The differentials need a C compiler; a run without one must declare
+ // it rather than skip. See globalSetup.ts.
+ globalSetup: ['tests/globalSetup.ts'],
+ },
resolve: {
alias: {
// So a test can import a real example system, whose own imports the
diff --git a/pipeline/tests/build-compiled-systems.test.ts b/pipeline/tests/build-compiled-systems.test.ts
index 7f8eeed83..726964316 100644
--- a/pipeline/tests/build-compiled-systems.test.ts
+++ b/pipeline/tests/build-compiled-systems.test.ts
@@ -344,10 +344,6 @@ describe('the AOT build step', () => {
* C at the other width, since the header picks the typedef.
*/
describe('the AOT build step, for a host that loads a library', () => {
- it('reports whether this gate could run at all', () => {
- if (!HOST_CC) console.warn('[aot-native] NO HOST C COMPILER — the native build did NOT run.');
- });
-
it.skipIf(!HOST_CC)('builds a library named for this platform, and a manifest for it', async () => {
const root = project({ 'src/components.ts': COMPONENTS, 'src/systems.ts': PROMISED });
const out = await buildCompiledSystems(root, { mode: 'release', target: 'native', cc: HOST_CC, run });
diff --git a/pipeline/tests/globalSetup.ts b/pipeline/tests/globalSetup.ts
new file mode 100644
index 000000000..80ef3ba55
--- /dev/null
+++ b/pipeline/tests/globalSetup.ts
@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file globalSetup.ts — the native AOT build is compiled here, so the
+ * machine has to have a compiler before the run claims it built one.
+ *
+ * @details Same owner as the compiler suite's prerequisite: a capability proved
+ * in one place, so the `skipIf`s below it mean what they say.
+ */
+import { proveHostCC } from '../../compiler/src/hostCC';
+
+export default async function setup(): Promise<void> {
+ proveHostCC('pipeline-tests');
+}
diff --git a/pipeline/vitest.config.ts b/pipeline/vitest.config.ts
index 012c50c43..0b38e6eb8 100644
--- a/pipeline/vitest.config.ts
+++ b/pipeline/vitest.config.ts
@@ -15,5 +15,8 @@ export default defineConfig({
// Cook and export shell out and touch temp directories.
testTimeout: 30_000,
hookTimeout: 30_000,
+ // The native AOT build needs a C compiler; a run without one must declare
+ // it rather than skip. See globalSetup.ts.
+ globalSetup: ['tests/globalSetup.ts'],
},
});
diff --git a/tools/check-suite-preconditions.mjs b/tools/check-suite-preconditions.mjs
new file mode 100644
index 000000000..7ea83d6f6
--- /dev/null
+++ b/tools/check-suite-preconditions.mjs
@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-suite-preconditions.mjs — a suite that CANNOT run its
+ * differentials has to say so, and be counted as not having run them.
+ *
+ * `it.skipIf(!CC)` reads in a summary exactly like a test that ran, and one
+ * suite did worse: an early `return` left twenty-two tests unregistered, so a
+ * machine with no compiler reported a smaller suite passing.
+ *
+ * The honest shape is a chain, and every link of it can be removed on its own
+ * without anything going red — which is what this holds together:
+ *
+ * probe → prover (once per suite) → declaration env var → the gate runner
+ *
+ * Run: node tools/check-suite-preconditions.mjs
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (p) => readFileSync(path.join(ROOT, p), 'utf8');
+
+/**
+ * A machine capability a test may be unable to exercise. `probe` answers
+ * whether the machine has it; `prover` is what a suite calls ONCE so a skip
+ * below it means "not applicable" rather than "never looked".
+ */
+const CAPABILITIES = [
+ { what: 'a host C compiler', probe: 'findHostCC', prover: 'proveHostCC', owner: 'compiler/src/hostCC.ts' },
+];
+
+/** Test files, by the package that owns them. */
+function testFiles(dir, out = []) {
+ for (const name of readdirSync(path.join(ROOT, dir))) {
+ if (name === 'node_modules') continue;
+ const child = `${dir}/${name}`;
+ if (statSync(path.join(ROOT, child)).isDirectory()) testFiles(child, out);
+ else if (name.endsWith('.test.ts')) out.push(child);
+ }
+ return out;
+}
+
+const SUITES = ['compiler/tests', 'pipeline/tests', 'sdk/tests'].filter((d) => existsSync(path.join(ROOT, d)));
+const problems = [];
+let checked = 0;
+
+for (const cap of CAPABILITIES) {
+ const owner = read(cap.owner);
+ // Word-bounded, and a CALL rather than a mention: `proveHostCCX` contains
+ // the name, and an import line contains it without anything invoking it.
+ if (!new RegExp(`export function ${cap.prover}\\b`).test(owner)) {
+ problems.push(`${cap.owner} no longer exports ${cap.prover}() — nothing proves ${cap.what}.`);
+ continue;
+ }
+
+ // 1. Every suite whose tests ask for the capability proves it once.
+ const users = new Set();
+ for (const dir of SUITES) {
+ for (const file of testFiles(dir)) {
+ if (read(file).includes(cap.probe)) users.add(dir.split('/')[0]);
+ }
+ }
+ if (users.size === 0) {
+ problems.push(`no test uses ${cap.probe} — this capability's rule has nothing to hold.`);
+ }
+ for (const pkg of [...users].sort()) {
+ checked++;
+ const config = `${pkg}/vitest.config.ts`;
+ const setup = /globalSetup:\s*\[\s*'([^']+)'/.exec(existsSync(path.join(ROOT, config)) ? read(config) : '');
+ if (!setup) {
+ problems.push(`${pkg} skips on ${cap.probe} but ${config} runs no globalSetup —`
+ + ` a machine without ${cap.what} reports those tests as a pass.`);
+ continue;
+ }
+ const at = `${pkg}/${setup[1]}`;
+ const calls = new RegExp(`\\b${cap.prover}\\s*\\(`);
+ if (!existsSync(path.join(ROOT, at)) || !calls.test(read(at))) {
+ problems.push(`${at} does not call ${cap.prover}() — ${pkg}'s skips on ${cap.probe} are silent.`);
+ }
+ }
+
+ // 2. The declaration a machine without it makes is one the gate runner counts
+ // as a hole. Two spellings of the env var and `--complete` stops seeing it.
+ const declared = /const NO_[A-Z_]+ = '([A-Z_]+)'/.exec(owner);
+ if (!declared) {
+ problems.push(`${cap.owner} does not name the env var a checkout without ${cap.what} declares.`);
+ } else if (!read('tools/run-gates.mjs').includes(`'${declared[1]}'`)) {
+ problems.push(`run-gates does not count ${declared[1]} as a gap, so declaring it would`
+ + ' hide the hole from --complete rather than report it.');
+ }
+}
+
+if (problems.length) {
+ console.error(`check-suite-preconditions: ${problems.length} finding(s).`);
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+console.log(`check-suite-preconditions: ${CAPABILITIES.length} capability/capabilities,`
+ + ` ${checked} suite(s) prove what their skips depend on.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 4fea59555..b72fa1377 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -208,6 +208,7 @@ export const GATES = [
{ id: 'verifier-owners', run: 'node tools/check-verifier-owners.mjs' },
{ id: 'electron-preconditions', run: 'node tools/check-electron-preconditions.mjs' },
{ id: 'unanswered-exits', run: 'node tools/check-unanswered-exits.mjs' },
+ { id: 'suite-preconditions', run: 'node tools/check-suite-preconditions.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/lib/contractFacts.mjs b/tools/lib/contractFacts.mjs
index 739826bf2..08e1d3e05 100644
--- a/tools/lib/contractFacts.mjs
+++ b/tools/lib/contractFacts.mjs
@@ -156,13 +156,11 @@ export const FACTS = [
// The half that needs no compiler: every constant the C half emits
// is the author's, in the author's order.
{ path: 'compiler/tests/exact-trig.test.ts', how: 'test', probe: /authored order/ },
+ // A differential that did not run is not a verification: the suite
+ // proves the machine can compile, or the run declares it cannot.
+ { path: 'compiler/tests/globalSetup.ts', how: 'test', probe: /proveHostCC\(/ },
],
digest: { name: 'engine-abi', path: 'sdk/src/ecs/aot/abiDigest.ts', probe: /trig=/ },
- owed: 'the constants are one author and therefore in the digest, but the STRUCTURE'
- + ' is still written twice and only the differential compares it — and that'
- + ' needs a host C compiler. A checkout without one holds the reduction, the'
- + ' quadrant table and the Horner order against nothing, and says so in a'
- + ' warning inside a test that passes.',
},
{
id: 'tweenWireEnums',
diff --git a/tools/run-gates.mjs b/tools/run-gates.mjs
index 5181fbffd..f6cf2c836 100644
--- a/tools/run-gates.mjs
+++ b/tools/run-gates.mjs
@@ -45,6 +45,22 @@ const SUITES = !argv.includes('--no-suites');
* leaving 0 — so the nightly read 69/69 green as an answer about 80.
*/
const COMPLETE = argv.includes('--complete');
+
+/**
+ * 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
+ * still a hole, and one only the summary knew about.
+ */
+const GAPS = [
+ { env: 'SDK_TEST_MODE', value: 'no-wasm', says: 'sdk-tests did NOT cover the engine boundary' },
+ {
+ env: 'ESTELLA_NO_HOST_CC',
+ value: '1',
+ says: 'no C compiler — the emitted C was NOT compared against the interpreter,'
+ + ' and the ABI struct checks were not compiled',
+ },
+];
+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. */
@@ -74,9 +90,7 @@ function reportSuites() {
if (suites.length) console.log(` test suites run: ${suites.map((g) => g.id).join(', ')}`);
// 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".
- if (process.env.SDK_TEST_MODE === 'no-wasm') {
- console.log(' SDK_TEST_MODE=no-wasm — sdk-tests did NOT cover the engine boundary');
- }
+ for (const g of declared) console.log(` ${g.env}=${g.value} — ${g.says}`);
const unrun = noEditor.filter((g) => g.covers?.length);
if (unrun.length) {
console.log(` test suites NOT run: ${unrun.map((g) => g.id).join(', ')} — no editor checkout`);
@@ -125,9 +139,15 @@ for (const g of skipped) console.log(` not in this scope: ${g.id} — ${g.why}`
// A gate narrowed to another scope is owned there and is not this run's hole;
// one dropped for a missing checkout or an unpaid minute is exactly that.
if (COMPLETE) {
- const absent = [...noEditor, ...unpaid];
- if (absent.length) {
- console.error(`\n${absent.length} declared gate(s) never ran here: ${absent.map((g) => g.id).join(', ')}`);
+ // A declaration is not permission: it is the same hole as a missing checkout,
+ // said out loud instead of found. Printing it while exiting 0 is the shape
+ // check-unanswered-exits refuses of every verifier but this one.
+ const holes = [
+ ...[...noEditor, ...unpaid].map((g) => g.id),
+ ...declared.map((g) => `${g.env}=${g.value}`),
+ ];
+ if (holes.length) {
+ console.error(`\n${holes.length} declared gate(s) or capability gap(s) never ran here: ${holes.join(', ')}`);
console.error(' --complete was asked for, so this cannot say the list is green.');
process.exit(2);
}