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
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file check-architecture-doc.mjs
* @brief The document that says what the engine IS names things that exist.
* @details `docs/ARCHITECTURE.md` calls itself descriptive of the current code,
* and nothing checked that. It drifted for six weeks: it described a 2D
* engine shipping only to browsers and WeChat, said the native seam had
* been closed by deletion while `native/` was building for three
* platforms, and named `Lit2D` and `Light2D` after both were renamed.
*
* Every convention in this repo that survives has a gate. This one takes
* the checkable half: every path in a backtick exists, and every code
* identifier in a backtick is somewhere in the sources. Prose it cannot
* judge, but a doc naming only live symbols is a doc someone maintained.
*
* REARCHITECTURE.md is deliberately NOT a subject: a plan names what does
* not exist yet, which is the whole point of it.
*
* Run: node tools/check-architecture-doc.mjs (exit 1 on a dead name)
*/
import { readFileSync, existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { listTrackedSources } from './lib/sourceRoots.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const DOC = path.join(ROOT, 'docs', 'ARCHITECTURE.md');
/** Where a name is allowed to live. A symbol anywhere in these is alive. */
const SOURCES = ['src', 'sdk/src', 'native', 'pipeline/src', 'editor-api', 'tools', 'build-tools', 'tests'];
const SOURCE_EXT = /\.(cpp|hpp|h|ts|tsx|mjs|js|json|cmake|txt|py)$/;
/** A bare `foo/` in this doc is a subdirectory of one of these. */
const DIR_ROOTS = ['src/esengine', 'sdk/src', 'docs', '.'];
/**
* Paths the doc may name that are not in this checkout: the companion plans that
* are gitignored on purpose, the optional editor, a build output, and a package
* entry specifier that is not a path at all.
*/
const ABSENT_BY_DESIGN = new Set([
'REARCH_2D_PARITY.md', 'REARCH_WGSL.md', 'desktop/',
'dist/index.native.bundled.js',
]);
/**
* `esengine/<name>` is a package entry specifier, not a path — and the set of them
* is published, so this reads it rather than keeping a second list. The doc can
* name a subpath only if the package actually exports one.
*/
const ENTRY_SPECIFIERS = new Set(
Object.keys(JSON.parse(readFileSync(path.join(ROOT, 'sdk', 'package.json'), 'utf8')).exports)
.filter((k) => k.startsWith('./'))
.map((k) => `esengine/${k.slice(2)}`));
/**
* Names the doc mentions BECAUSE they are gone. Asserted in the other direction:
* if one comes back, the sentence saying it was deleted has quietly become false.
*/
const GONE = new Set(['getTypeId', 'DynamicComponentPool', 'SchemaComponentPool', 'BatchRenderer2D']);
const SELF = 'tools/check-architecture-doc.mjs';
/**
* The index, not the disk. An export leaves gitignored bundles under
* `pipeline/src`, and a walk that reads those judges the doc against a bundle of
* the sources rather than the sources — which revived `getTypeId` and turned this
* gate red on any machine that had run one.
*/
const { files: tracked, missing } = listTrackedSources(SOURCES);
if (missing.length > 0) {
console.error(`check-architecture-doc: no checkout to read for ${missing.join(', ')}`);
console.error('A gate that cannot see part of its corpus must not report on it.');
process.exit(2);
}
const haystack = tracked
// This file names every dead symbol on purpose; reading it would revive them all.
.filter((f) => f !== SELF && SOURCE_EXT.test(f))
.map((f) => readFileSync(path.join(ROOT, f), 'utf8'))
.join('\n');
const doc = readFileSync(DOC, 'utf8');
const problems = [];
const lineOf = (index) => doc.slice(0, index).split('\n').length;
for (const m of doc.matchAll(/`([^`\n]+)`/g)) {
const raw = m[1].trim();
// A path: what it points at has to be there. Line suffixes are how this repo
// cites code, and a range of them is still one file.
if (/^[\w./-]+\/[\w./-]*$/.test(raw) || /^[\w-]+\.(md|ts|mjs|cpp|hpp|json|esshader)$/.test(raw)) {
const bare = raw.replace(/:[\d,\-\s]+$/, '');
if (ABSENT_BY_DESIGN.has(bare) || ABSENT_BY_DESIGN.has(`${bare}/`)) continue;
if (ENTRY_SPECIFIERS.has(bare)) continue;
if (existsSync(path.join(ROOT, bare))) continue;
if (DIR_ROOTS.some((r) => existsSync(path.join(ROOT, r, bare)))) continue;
// A bare filename is cited without its directory all over the doc.
if (!bare.includes('/') && haystack.includes(bare)) continue;
problems.push(`${lineOf(m.index)}: \`${raw}\` — no such path`);
continue;
}
// An identifier: CamelCase or snake_case, nothing a sentence would contain.
const bare = raw.replace(/^[&*]+/, '').replace(/[(<].*$/, '').replace(/^.*::/, '');
if (!/^[A-Za-z_][A-Za-z0-9_]{2,}$/.test(bare)) continue;
if (!/[a-z][A-Z]|_/.test(bare)) continue;
if (GONE.has(bare)) continue;
if (haystack.includes(bare)) continue;
problems.push(`${lineOf(m.index)}: \`${raw}\` — names nothing in the sources`);
}
// The other direction: a name the doc says is gone, that is back.
for (const name of GONE) {
if (!doc.includes(name)) {
problems.push(`GONE lists \`${name}\`, which the doc no longer mentions — drop it from the list`);
// Declared or called, not merely named: a comment recalling why something went
// is exactly the trace a deletion leaves behind.
} else if (new RegExp(`\\b(class|struct|interface|enum|type)\\s+${name}\\b|\\b${name}\\s*[(<]`).test(haystack)) {
problems.push(`\`${name}\` is in the sources again; the doc says it was removed`);
}
}
if (problems.length > 0) {
console.error('docs/ARCHITECTURE.md describes code that is not there:\n');
for (const p of problems) console.error(` ${p}`);
console.error('\nThe file says it is descriptive of the current code. Update it, or'
+ ' move the claim to REARCHITECTURE.md, where a plan belongs.');
process.exit(1);
}
const names = (doc.match(/`[^`\n]+`/g) ?? []).length;
console.log(`check-architecture-doc: ${names} name(s) in docs/ARCHITECTURE.md — every path exists`
+ ' and every identifier is in the sources.');