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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file check-cycles.mjs — an import-cycle ratchet.
*
* A cycle between modules is not a style problem: ESM initializes a cycle's
* members in an order nobody wrote down, so a `const` read during another
* module's top-level evaluation is `undefined` rather than an error. That is the
* failure mode behind "the component lost its identity after a re-import" and
* behind resolvers that silently never run.
*
* ONLY VALUE IMPORTS COUNT. `import type` is erased before the module ever
* exists, so a type-level cycle cannot misinitialize anything — counting them
* (madge's default) reports dozens of "cycles" that no runtime has. Two modules
* naming each other's types is normal and is not a defect to chase.
*
* Cycles are counted per entry and compared against `BUDGETS` below. Going OVER
* fails; coming in UNDER also fails, with the instruction to lower the budget —
* a ratchet only holds if it cannot silently slip back up after someone pays to
* bring it down.
*/
import madge from 'madge';
import path from 'node:path';
import { existsSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
// Lower these as cycles are broken; never raise them.
//
// The editor's remaining one is EngineHost → SceneLoader → Reconciler →
// EngineHost, and it is PRINCIPLED rather than pending: the three are one
// collaboration around the live World — the host owns it, the loader loads into
// it, the reconciler projects the scene model into it. Breaking it means either
// leaking the App out of EngineHost (worse encapsulation, for one caller) or
// threading a world argument through six modules of call sites. Both are worse
// than the cycle. Judge a NEW cycle on its own merits; do not read this budget
// as permission for one.
const BUDGETS = [
{ name: 'sdk', entry: 'sdk/src/index.ts', tsconfig: 'sdk', extensions: ['ts'], budget: 0 },
{ name: 'editor', entry: 'desktop/src/main.tsx', tsconfig: 'desktop', extensions: ['ts', 'tsx'], budget: 1 },
];
let failed = false;
for (const { name, entry, tsconfig, extensions, budget } of BUDGETS) {
// The editor is an optional submodule; an absent entry is nothing to measure.
// Said out loud, because a budget that silently stops being checked is a budget
// that always passes.
if (!existsSync(path.join(ROOT, entry))) {
console.log(`${name.padEnd(7)} — not checked out, no cycles measured`);
continue;
}
const res = await madge(path.join(ROOT, entry), {
fileExtensions: extensions,
tsConfig: path.join(ROOT, tsconfig, 'tsconfig.json'),
detectiveOptions: { ts: { skipTypeImports: true }, tsx: { skipTypeImports: true } },
});
const cycles = res.circular();
const n = cycles.length;
const verdict = n > budget ? 'OVER' : n < budget ? 'UNDER' : 'ok';
console.log(`${name.padEnd(7)} ${String(n).padStart(3)} cycles (budget ${budget}) — ${verdict}`);
if (n > budget) {
failed = true;
console.log(` ${n - budget} new cycle(s). The shortest ones are usually the real edge:`);
for (const c of [...cycles].sort((a, b) => a.length - b.length).slice(0, 5)) {
console.log(` ${c.join(' → ')} → ${c[0]}`);
}
} else if (n < budget) {
failed = true;
console.log(` Cycles were removed — lower ${name}'s budget to ${n} in tools/check-cycles.mjs.`);
}
}
if (failed) process.exit(1);
console.log('check-cycles: all entries within budget.');