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(tools): the plugins we ship are held to what a third party can reach

yhh1fcbc0282008
diff --git a/tools/check-plugin-boundary.mjs b/tools/check-plugin-boundary.mjs
new file mode 100644
index 000000000..3f5ee1054
--- /dev/null
+++ b/tools/check-plugin-boundary.mjs
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-plugin-boundary.mjs — the plugins we ship stay on the public side.
+ *
+ * A plugin in this repo sits next to the engine, so nothing stops it importing
+ * `../../desktop/src/...` and working perfectly — here. Published, that import
+ * resolves to nothing, and the API it was meant to prove was never exercised.
+ *
+ * So the plugins are held to what a third party can reach: their own files, and
+ * packages. Anything naming this repo's internals is refused.
+ *
+ * node tools/check-plugin-boundary.mjs
+ */
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PLUGINS = path.join(ROOT, 'plugins');
+const SOURCE = /\.(ts|tsx|js|jsx|mjs)$/;
+
+/** Import/require/export-from specifiers, in source order. */
+const SPECIFIERS = [
+ /\bfrom\s+['"]([^'"]+)['"]/g,
+ /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+ /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+
+/**
+ * Why this specifier is not something a published plugin could resolve, or null.
+ * `file` and `pkgDir` are absolute.
+ */
+function problem(spec, file, pkgDir) {
+ if (spec.startsWith('.')) {
+ const target = path.resolve(path.dirname(file), spec);
+ return target.startsWith(pkgDir + path.sep) || target === pkgDir
+ ? null
+ : 'reaches outside the package — published, that path does not exist';
+ }
+ // A bare specifier is a package, which is fine — unless it names this repo.
+ if (/^@\//.test(spec)) return 'the editor\'s own path alias — plugins have no such alias';
+ if (/(^|\/)(desktop|sdk)\/src\//.test(spec)) return 'imports engine/editor sources directly';
+ if (/^esengine\/dist\b/.test(spec)) return 'reaches into the SDK build — import `esengine` (or a documented subpath)';
+ return null;
+}
+
+function walk(dir, out = []) {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) walk(full, out);
+ else if (SOURCE.test(entry.name)) out.push(full);
+ }
+ return out;
+}
+
+const findings = [];
+const packages = existsSync(PLUGINS)
+ ? readdirSync(PLUGINS).filter((n) => statSync(path.join(PLUGINS, n)).isDirectory())
+ : [];
+
+for (const name of packages) {
+ const pkgDir = path.join(PLUGINS, name);
+ for (const file of walk(pkgDir)) {
+ const text = readFileSync(file, 'utf8');
+ const lines = text.split('\n');
+ for (let i = 0; i < lines.length; i++) {
+ for (const re of SPECIFIERS) {
+ re.lastIndex = 0;
+ let m;
+ while ((m = re.exec(lines[i])) !== null) {
+ const why = problem(m[1], file, pkgDir);
+ if (why) findings.push({ file: path.relative(ROOT, file), line: i + 1, spec: m[1], why });
+ }
+ }
+ }
+ }
+}
+
+if (findings.length === 0) {
+ console.log(`check-plugin-boundary: ${packages.length} plugin(s) — every import is one a published plugin can resolve.`);
+ process.exit(0);
+}
+for (const f of findings) {
+ console.error(`${f.file}:${f.line} "${f.spec}" ${f.why}`);
+}
+console.error(`\ncheck-plugin-boundary: ${findings.length} finding(s).`);
+process.exit(1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 50a313120..23b13a280 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -54,6 +54,8 @@ export const GATES = [
// could survive fails here rather than in someone else's project.
{ id: 'tsc-plugins', run: 'pnpm -r --filter "./plugins/*" exec tsc --noEmit' },
{ id: 'plugin-tests', run: 'pnpm -r --filter "./plugins/*" test' },
+ // The plugins we ship prove the public API only if they are held to it.
+ { id: 'plugin-boundary', run: 'node tools/check-plugin-boundary.mjs' },
{ id: 'cycles', run: 'node tools/check-cycles.mjs' },
{ id: 'layers', run: 'node tools/check-layers.mjs' },
{ id: 'project-settings', run: 'node tools/check-project-settings.mjs' },