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): the comment scan reads the editor too, and says what it read
esengine73d3473602fe
diff --git a/.gitmodules b/.gitmodulesindex f543aa83b..3bf082b1e 100644--- a/.gitmodules+++ b/.gitmodules@@ -1,9 +1,11 @@[submodule "third_party/glm"]path = third_party/glmurl = https://github.com/g-truc/glm.git+ estella-corpus = vendored[submodule "third_party/glfw"]path = third_party/glfwurl = https://github.com/glfw/glfw.git+ estella-corpus = vendored[submodule "third_party/spine-runtimes-3.8"]path = third_party/spine-runtimes-3.8url = https://github.com/EsotericSoftware/spine-runtimes.git@@ -11,9 +13,11 @@# Vendored and read-only: an uninitialised nested example directory is not# a change to this repo, and reporting it as one only invites a stray commit.ignore = untracked+ estella-corpus = vendored[submodule "third_party/box2d"]path = third_party/box2durl = https://github.com/erincatto/box2d.git+ estella-corpus = vendored[submodule "third_party/spine-runtimes-4.1"]path = third_party/spine-runtimes-4.1url = https://github.com/EsotericSoftware/spine-runtimes.git@@ -21,6 +25,7 @@# Vendored and read-only: an uninitialised nested example directory is not# a change to this repo, and reporting it as one only invites a stray commit.ignore = untracked+ estella-corpus = vendored[submodule "third_party/spine-runtimes-4.2"]path = third_party/spine-runtimes-4.2url = https://github.com/EsotericSoftware/spine-runtimes.git@@ -28,15 +33,19 @@# Vendored and read-only: an uninitialised nested example directory is not# a change to this repo, and reporting it as one only invites a stray commit.ignore = untracked+ estella-corpus = vendored[submodule "third_party/basis_universal"]path = third_party/basis_universalurl = https://github.com/BinomialLLC/basis_universal.git+ estella-corpus = vendored[submodule "tools/emsdk"]path = tools/emsdkurl = https://github.com/emscripten-core/emsdk.git+ estella-corpus = vendored[submodule "third_party/glslang"]path = third_party/glslangurl = https://github.com/KhronosGroup/glslang+ estella-corpus = vendored[submodule "third_party/spine-runtimes-4.3"]path = third_party/spine-runtimes-4.3url = https://github.com/EsotericSoftware/spine-runtimes.git@@ -44,12 +53,14 @@# Vendored and read-only: an uninitialised nested example directory is not# a change to this repo, and reporting it as one only invites a stray commit.ignore = untracked+ estella-corpus = vendored[submodule "third_party/spine-runtimes-2.1"]path = third_party/spine-runtimes-2.1url = https://github.com/EsotericSoftware/spine-runtimes.git# Vendored and read-only: an uninitialised nested example directory is not# a change to this repo, and reporting it as one only invites a stray commit.ignore = untracked+ estella-corpus = vendored[submodule "desktop"]path = desktopurl = https://github.com/esengine/estella-editor.git@@ -58,3 +69,4 @@# skips the eight gates whose subject is the editor and names them, and# verify-render --host engine runs 100 of the 108 pixel gates. Do not make# anything engine-side require this path to exist.+ estella-corpus = sourcediff --git a/tools/check-comment-style.mjs b/tools/check-comment-style.mjsindex 016de420f..27d7ecc88 100644--- a/tools/check-comment-style.mjs+++ b/tools/check-comment-style.mjs@@ -16,10 +16,11 @@* node tools/check-comment-style.mjs added lines vs origin/master* node tools/check-comment-style.mjs --all whole tree (reporting only)*/-import { execFileSync } from 'node:child_process';import { readFileSync } from 'node:fs';import path from 'node:path';import { fileURLToPath } from 'node:url';+import { corpusRoots, censusFindings, trackedFiles, untrackedFiles, addedDiff }+ from './lib/sourceCensus.mjs';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');const SOURCE = /\.(ts|tsx|mjs|js|cpp|hpp|h)$/;@@ -68,14 +69,13 @@ function docRefs(text) {* means the question could not be asked, and a scan that cannot ask must not* answer green.*/+const ROOTS = corpusRoots();+const CENSUS = censusFindings(ROOTS);+const TRACKED = (() => {- let out = '';- try {- out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });- } catch { /* reported below */ }- const files = out.split('\n').filter(Boolean);+ const files = ROOTS.flatMap((r) => trackedFiles(r));if (files.length === 0) {- console.error('check-comment-style: `git ls-files` gave nothing — cannot judge doc references.');+ console.error('check-comment-style: the census is empty — cannot judge doc references.');process.exit(2);}return new Set([...files, ...files.map((f) => f.slice(f.lastIndexOf('/') + 1))]);@@ -86,57 +86,50 @@ function isTracked(ref) {return TRACKED.has(clean) || TRACKED.has(clean.slice(clean.lastIndexOf('/') + 1));}-/** Added lines per file, as [lineNumber, text]. */-function addedLines() {- let base = '';- for (const ref of ['origin/master', 'master']) {- try {- base = execFileSync('git', ['merge-base', 'HEAD', ref], { cwd: ROOT, encoding: 'utf8' }).trim();- break;- } catch { /* try the next ref */ }- }- const args = base ? ['diff', '-U0', base, '--'] : ['diff', '-U0', 'HEAD', '--'];- const diff = execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });+/** Every line of `file`, as [lineNumber, text] — a new file is all added. */+function wholeFile(byFile, f) {+ try {+ byFile.set(f, readFileSync(path.join(ROOT, f), 'utf8').split('\n').map((t, i) => [i + 1, t]));+ } catch { /* vanished between listing and reading */ }+}+/** Added lines per file, as [lineNumber, text], across every corpus root. */+function addedLines() {const byFile = new Map();- // A file git has never seen produces no diff, and a brand-new file is exactly- // where prose collects — every line of it is added.- const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard'],- { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });- for (const f of untracked.split('\n')) {- if (!f || SKIP.test(f) || !SOURCE.test(f)) continue;- try {- byFile.set(f, readFileSync(path.join(ROOT, f), 'utf8').split('\n').map((t, i) => [i + 1, t]));- } catch { /* vanished between listing and reading */ }- }- let file = null;- let line = 0;- for (const raw of diff.split('\n')) {- if (raw.startsWith('+++ b/')) {- file = raw.slice(6).trim();- if (SKIP.test(file) || !SOURCE.test(file)) file = null;- continue;+ for (const root of ROOTS) {+ // A file git has never seen produces no diff, and a brand-new file is exactly+ // where prose collects — every line of it is added.+ for (const f of untrackedFiles(root)) {+ if (!SKIP.test(f) && SOURCE.test(f)) wholeFile(byFile, f);}- const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);- if (hunk) { line = Number(hunk[1]); continue; }- if (!file) continue;- if (raw.startsWith('+')) {- if (!byFile.has(file)) byFile.set(file, []);- byFile.get(file).push([line, raw.slice(1)]);- line++;+ let file = null;+ let line = 0;+ for (const raw of addedDiff(root, ['-U0']).split('\n')) {+ if (raw.startsWith('+++ b/')) {+ const named = root.prefix ? `${root.prefix}/${raw.slice(6).trim()}` : raw.slice(6).trim();+ file = SKIP.test(named) || !SOURCE.test(named) ? null : named;+ continue;+ }+ const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);+ if (hunk) { line = Number(hunk[1]); continue; }+ if (!file) continue;+ if (raw.startsWith('+')) {+ if (!byFile.has(file)) byFile.set(file, []);+ byFile.get(file).push([line, raw.slice(1)]);+ line++;+ }}}return byFile;}function allLines() {- const listed = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });const byFile = new Map();- for (const f of listed.split('\n')) {- if (!f || SKIP.test(f) || !SOURCE.test(f)) continue;- let text;- try { text = readFileSync(path.join(ROOT, f), 'utf8'); } catch { continue; }- byFile.set(f, text.split('\n').map((t, i) => [i + 1, t]));+ for (const root of ROOTS) {+ for (const f of trackedFiles(root)) {+ if (SKIP.test(f) || !SOURCE.test(f)) continue;+ wholeFile(byFile, f);+ }}return byFile;}@@ -221,10 +214,26 @@ function scan(byFile) {}const all = process.argv.includes('--all');-const findings = scan(all ? allLines() : addedLines());+const lines = all ? allLines() : addedLines();+const findings = scan(lines);++/** What the run READ, so "clean" is attached to a corpus rather than to silence. */+const present = ROOTS.filter((r) => r.present);+const absent = ROOTS.filter((r) => !r.present).map((r) => r.prefix);+const read = `${lines.size} file(s) across ${present.length} repositor${present.length === 1 ? 'y' : 'ies'}`+ + (absent.length ? `, and none in ${absent.join(', ')} — not checked out` : '');++// A census that could not look is not a style opinion, so it fails even under+// --all: the whole failure mode here is a green run that read nothing.+if (CENSUS.length) {+ for (const f of CENSUS) console.error(` - ${f}`);+ console.error(`\ncheck-comment-style: ${CENSUS.length} problem(s) with the corpus itself.`);+ process.exit(1);+}if (findings.length === 0) {- console.log(`check-comment-style: ${all ? 'tree' : 'added lines'} clean — comments state contracts, not stories.`);+ console.log(`check-comment-style: ${all ? 'tree' : 'added lines'} clean — ${read}; `+ + 'comments state contracts, not stories.');process.exit(0);}@@ -240,5 +249,6 @@ for (const [file, fs] of byFile) {if (f.text) console.error(` ${f.text}`);}}-console.error(`\ncheck-comment-style: ${findings.length} finding(s). See docs/CODE_COMMENTS.md.`);+console.error(`\ncheck-comment-style: ${findings.length} finding(s) in ${read}. `+ + 'See docs/CODE_COMMENTS.md.');process.exit(all ? 0 : 1);diff --git a/tools/lib/sourceCensus.mjs b/tools/lib/sourceCensus.mjsnew file mode 100644index 000000000..acfd9f6d5--- /dev/null+++ b/tools/lib/sourceCensus.mjs@@ -0,0 +1,118 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file sourceCensus.mjs — the files a repository-wide scan is entitled to say+ * it looked at.+ *+ * `git ls-files` from the root sees NOTHING inside a submodule, and an empty+ * corpus reads exactly like a clean one. The editor is a submodule, so every+ * scan that judged "the repository" judged the engine half of it and reported+ * green about the other half without ever opening a file there.+ *+ * The roots come from `.gitmodules`, which is where submodules are declared, and+ * each one has to say which corpus it belongs to — `source` is ours and is+ * scanned, `vendored` is somebody else's and is not. A submodule that says+ * neither is a finding: a new one must not join the tree unscanned by silence.+ */+import { execFileSync } from 'node:child_process';+import { existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');++/** The key every submodule in `.gitmodules` owes, and the value that means ours. */+const CORPUS_KEY = 'estella-corpus';+const OURS = 'source';++const git = (dir, args, max = 256 * 1024 * 1024) =>+ execFileSync('git', args, { cwd: dir, encoding: 'utf8', maxBuffer: max });++/**+ * Every submodule `.gitmodules` declares, with the corpus it claims.+ *+ * Read with `git config -f`, so the parse is git's own rather than a second one+ * that could disagree with it about the file it is looking at.+ */+function declaredSubmodules() {+ let out = '';+ try {+ out = git(ROOT, ['config', '-f', '.gitmodules', '--list']);+ } catch { /* no submodules at all — reported by the caller as an empty census */ }+ const byName = new Map();+ for (const line of out.split('\n')) {+ const m = /^submodule\.(.+)\.([^.=]+)=(.*)$/.exec(line);+ if (!m) continue;+ const [, name, key, value] = m;+ if (!byName.has(name)) byName.set(name, { name });+ if (key === 'path') byName.get(name).path = value;+ if (key === CORPUS_KEY) byName.get(name).corpus = value;+ }+ return [...byName.values()];+}++/**+ * The repositories a scan spans: this one, then every submodule that says it+ * holds our source. `present` is false for one that is declared and not checked+ * out — an optional product, which a scan must name rather than quietly omit.+ */+export function corpusRoots() {+ const roots = [{ prefix: '', dir: ROOT, present: true }];+ for (const sub of declaredSubmodules()) {+ if (sub.corpus !== OURS || !sub.path) continue;+ const dir = path.join(ROOT, sub.path);+ roots.push({ prefix: sub.path, dir, present: existsSync(path.join(dir, '.git')) });+ }+ return roots;+}++/**+ * What is wrong with the census itself, before anything it holds is judged.+ *+ * A declared submodule with no `estella-corpus`, and a present root that yields+ * no files, are the two ways this reports green having read nothing.+ */+export function censusFindings(roots) {+ const findings = [];+ for (const sub of declaredSubmodules()) {+ if (!sub.corpus) {+ findings.push(`.gitmodules declares "${sub.name}" without ${CORPUS_KEY} — `+ + `say \`${CORPUS_KEY} = ${OURS}\` to have it scanned, or \`= vendored\` to say why not`);+ }+ }+ for (const root of roots) {+ if (root.present && trackedFiles(root).length === 0) {+ findings.push(`the corpus at "${root.prefix || '.'}" is checked out and holds no tracked `+ + 'file — the scan below would have judged nothing and said so as green');+ }+ }+ return findings;+}++/** Every tracked path in `root`, prefixed so it names a file from the repo root. */+export function trackedFiles(root) {+ if (!root.present) return [];+ let out = '';+ try { out = git(root.dir, ['ls-files']); } catch { return []; }+ return out.split('\n').filter(Boolean).map((f) => (root.prefix ? `${root.prefix}/${f}` : f));+}++/** Untracked, un-ignored paths in `root`, prefixed the same way. */+export function untrackedFiles(root) {+ if (!root.present) return [];+ let out = '';+ try { out = git(root.dir, ['ls-files', '--others', '--exclude-standard'], 64 * 1024 * 1024); }+ catch { return []; }+ return out.split('\n').filter(Boolean).map((f) => (root.prefix ? `${root.prefix}/${f}` : f));+}++/** `git diff` output for what `root` has added since it left the remote. */+export function addedDiff(root, args) {+ if (!root.present) return '';+ let base = '';+ for (const ref of ['origin/master', 'master']) {+ try { base = git(root.dir, ['merge-base', 'HEAD', ref]).trim(); break; } catch { /* next */ }+ }+ try { return git(root.dir, ['diff', ...args, ...(base ? [base] : ['HEAD']), '--']); }+ catch { return ''; }+}diff --git a/tools/tests/source-census.test.ts b/tools/tests/source-census.test.tsnew file mode 100644index 000000000..d42e6eee9--- /dev/null+++ b/tools/tests/source-census.test.ts@@ -0,0 +1,48 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file source-census.test.ts — what a repository-wide scan is entitled to say+ * it read.+ *+ * The editor lives in a submodule, and `git ls-files` from the root sees nothing+ * inside one. Every scan that judged "the repository" judged half of it.+ */+import { describe, it, expect } from 'vitest';+// @ts-expect-error — a repo tool, shipped as .mjs with no declarations+import { corpusRoots, censusFindings, trackedFiles } from '../lib/sourceCensus.mjs';++type Root = { prefix: string; present: boolean };++describe('the source census spans this repository and the submodules that hold our source', () => {+ const roots: Root[] = corpusRoots();++ // Independent of whether the optional editor is checked out: a scan has to+ // KNOW about a corpus before it can say it looked at one or that it could not.+ it('names the root and the editor, and nothing vendored', () => {+ expect(roots.map((r) => r.prefix)).toEqual(['', 'desktop']);+ });++ it('reads the root corpus, which is where the engine is', () => {+ const root = roots.find((r) => r.prefix === '')!;+ expect(trackedFiles(root).length).toBeGreaterThan(1000);+ });++ // Every submodule declares which corpus it is in, so a new one cannot join+ // the tree and go unscanned by silence.+ it('holds every declared submodule to saying which corpus it is in', () => {+ expect(censusFindings(roots)).toEqual([]);+ });++ it('prefixes a submodule file so it names one path from the repo root', () => {+ const editor = roots.find((r) => r.prefix === 'desktop')!;+ const files: string[] = trackedFiles(editor);+ // A checkout without the editor reads none, and says so rather than+ // reporting the empty list as a corpus it examined.+ if (!editor.present) {+ expect(files).toEqual([]);+ return;+ }+ expect(files.length).toBeGreaterThan(100);+ expect(files.every((f) => f.startsWith('desktop/'))).toBe(true);+ });+});