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
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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 thediff --git a/pipeline/tests/build-compiled-systems.test.ts b/pipeline/tests/build-compiled-systems.test.tsindex 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.tsnew file mode 100644index 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.tsindex 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.mjsnew file mode 100644index 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.mjsindex 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 builddiff --git a/tools/lib/contractFacts.mjs b/tools/lib/contractFacts.mjsindex 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.mjsindex 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);}