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(ci): read SDK exports from sdk/src, not the gitignored dist

esengine1cff30f1663a
diff --git a/docs/SITE.md b/docs/SITE.md
index 7c561a859..eaeaffc92 100644
--- a/docs/SITE.md
+++ b/docs/SITE.md
@@ -96,8 +96,8 @@ This will:
3. Add to sidebar in `astro/astro.config.mjs`
4. Keep code samples accurate: every symbol a guide imports from the main `esengine`
barrel must be a real SDK export. `npm run verify:imports` (from `docs/astro/`)
- checks this against `sdk/dist/index.d.ts` and runs in CI before the site build, so
- a renamed or fabricated API fails the docs deploy.
+ checks this against the exports declared in `sdk/src` and runs in CI before the
+ site build, so a renamed or fabricated API fails the docs deploy.
### Available Components
diff --git a/docs/astro/scripts/verify-doc-imports.mjs b/docs/astro/scripts/verify-doc-imports.mjs
index 2fea6988f..24817b45f 100644
--- a/docs/astro/scripts/verify-doc-imports.mjs
+++ b/docs/astro/scripts/verify-doc-imports.mjs
@@ -5,10 +5,13 @@
* @brief Guard against documentation API drift: every symbol the guides import
* from the main `esengine` barrel must be a real SDK export.
*
- * Reads the committed public type surface (`sdk/dist/index.d.ts`) and every
- * `import { … } from 'esengine'` in the docs, and fails if a guide references a
- * symbol the SDK doesn't export (a renamed / removed / fabricated API). Subpath
- * imports (`esengine/physics`, …) are out of scope — this checks the main barrel.
+ * Scans the SDK source (`sdk/src`, always present in the docs CI checkout — the
+ * built `dist/` is gitignored) for every exported identifier, and fails if a guide
+ * imports a symbol from the main `esengine` barrel that the SDK never exports (a
+ * renamed / removed / fabricated API). The source scan is a *superset* of the barrel
+ * (it also sees internal exports), so the check only ever errs toward NOT blocking —
+ * it never fails a guide that uses a real API. Subpath imports (`esengine/physics`,
+ * …) are out of scope — this checks the main barrel.
*/
import { readFileSync, readdirSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
@@ -16,25 +19,39 @@ import { dirname, join, relative } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const DOCS = join(here, '..', 'src', 'content', 'docs');
-const DTS = join(here, '..', '..', '..', 'sdk', 'dist', 'index.d.ts');
+const SDK_SRC = join(here, '..', '..', '..', 'sdk', 'src');
-/** Collect the names the bundled d.ts exports. */
+/** Recursively list .ts source files (skipping .d.ts and tests). */
+function tsFiles(dir) {
+ const out = [];
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
+ const p = join(dir, e.name);
+ if (e.isDirectory()) out.push(...tsFiles(p));
+ else if (e.name.endsWith('.ts') && !e.name.endsWith('.d.ts') && !e.name.endsWith('.test.ts')) out.push(p);
+ }
+ return out;
+}
+
+/** Collect every exported identifier declared or re-exported anywhere under sdk/src. */
function sdkExports() {
- let dts;
+ const names = new Set();
+ const add = (n) => { if (/^[A-Za-z_$][\w$]*$/.test(n)) names.add(n); };
+ let files;
try {
- dts = readFileSync(DTS, 'utf8');
+ files = tsFiles(SDK_SRC);
} catch {
- console.error(`✖ cannot read ${relative(process.cwd(), DTS)} — build the SDK first (pnpm --filter ./sdk build).`);
+ console.error(`✖ cannot read ${relative(process.cwd(), SDK_SRC)} — is the SDK checked out?`);
process.exit(2);
}
- const names = new Set();
- const add = (n) => { if (/^[A-Za-z_$][\w$]*$/.test(n)) names.add(n); };
- for (const m of dts.matchAll(/export\s+declare\s+(?:abstract\s+)?(?:class|function|const|let|var|enum)\s+([A-Za-z_$][\w$]*)/g)) add(m[1]);
- for (const m of dts.matchAll(/export\s+(?:interface|type)\s+([A-Za-z_$][\w$]*)/g)) add(m[1]);
- for (const blk of dts.matchAll(/export\s*\{([^}]*)\}/g)) {
- for (let part of blk[1].split(',')) {
- part = part.trim().replace(/^type\s+/, '');
- if (part) add(part.split(/\s+as\s+/).pop().trim());
+ for (const f of files) {
+ const src = readFileSync(f, 'utf8');
+ for (const m of src.matchAll(/export\s+(?:declare\s+)?(?:abstract\s+)?(?:class|function|const|let|var|enum|interface|type)\s+([A-Za-z_$][\w$]*)/g)) add(m[1]);
+ // export { A, B as C, type D } [from '…']
+ for (const blk of src.matchAll(/export\s*\{([^}]*)\}/g)) {
+ for (let part of blk[1].split(',')) {
+ part = part.trim().replace(/^type\s+/, '');
+ if (part) add(part.split(/\s+as\s+/).pop().trim());
+ }
}
}
return names;