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(gates): the comment scan reads the editor too, and says what it read

esengine73d3473602fe
diff --git a/.gitmodules b/.gitmodules
index f543aa83b..3bf082b1e 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,9 +1,11 @@
[submodule "third_party/glm"]
path = third_party/glm
url = https://github.com/g-truc/glm.git
+ estella-corpus = vendored
[submodule "third_party/glfw"]
path = third_party/glfw
url = https://github.com/glfw/glfw.git
+ estella-corpus = vendored
[submodule "third_party/spine-runtimes-3.8"]
path = third_party/spine-runtimes-3.8
url = 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/box2d
url = https://github.com/erincatto/box2d.git
+ estella-corpus = vendored
[submodule "third_party/spine-runtimes-4.1"]
path = third_party/spine-runtimes-4.1
url = 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.2
url = 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_universal
url = https://github.com/BinomialLLC/basis_universal.git
+ estella-corpus = vendored
[submodule "tools/emsdk"]
path = tools/emsdk
url = https://github.com/emscripten-core/emsdk.git
+ estella-corpus = vendored
[submodule "third_party/glslang"]
path = third_party/glslang
url = https://github.com/KhronosGroup/glslang
+ estella-corpus = vendored
[submodule "third_party/spine-runtimes-4.3"]
path = third_party/spine-runtimes-4.3
url = 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.1
url = 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 = desktop
url = 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 = source
diff --git a/tools/check-comment-style.mjs b/tools/check-comment-style.mjs
index 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.mjs
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ });
+});