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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file check-workflows.mjs — a job that runs the repo's tooling installed it first.
*
* `node build-tools/cli.js` and `pnpm` are not standalone binaries: they resolve
* out of the workspace's own `node_modules`. A job that reaches for them without
* `./.github/actions/setup` does not misbehave subtly — it dies on
* "Cannot find package 'commander'", and only once a tag is pushed, because the
* release path has no pull-request run to fail on first.
*
* That has now happened twice. `publish-templates` wrote the template index that
* way, and the fix left a comment saying so; the v0.37.0 publish gate then hand
* -rolled `actions/setup-node` (which installs nothing) two hundred lines below
* that comment and stranded a complete, correct release as a draft. A comment
* cannot fail a build. This can.
*
* The rule is deliberately narrow, and holds without exception: if a step runs
* workspace tooling, the job used the composite setup action, before that step,
* with its install. Everything else about a workflow is left alone.
*/
import { readdirSync, readFileSync, existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { GATES, SCOPES } from './gates.mjs';
const WORKFLOWS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '.github', 'workflows');
const SETUP = './.github/actions/setup';
// Commands that resolve out of the workspace's node_modules. `npm` is absent on
// purpose: docs/ installs its own tree with it and owes this repo's nothing.
const NEEDS_INSTALL = [
/\bnode\s+build-tools\//,
/\bnode\s+tools\//,
/\bpnpm\b/,
/\bnpx\b/,
];
/**
* The `run:` scripts of a workflow, as {line, text} where `line` is that of the
* script's FIRST line — the `run:` itself when inline, the line below it for a
* block scalar. Block scalars are joined so a command is matched wherever it
* sits in one, and comments never are.
*/
function runScripts(lines) {
const out = [];
for (let i = 0; i < lines.length; i++) {
const m = /^(\s*)(?:-\s+)?run:\s*(.*)$/.exec(lines[i]);
if (!m) continue;
const indent = m[1].length + (/^\s*-\s+/.test(lines[i]) ? 2 : 0);
const rest = m[2].trim();
if (rest && !/^[|>][-+]?\d*$/.test(rest)) {
out.push({ line: i + 1, text: rest });
continue;
}
const body = [];
let j = i + 1;
for (; j < lines.length; j++) {
if (lines[j].trim() === '') { body.push(''); continue; }
const lead = /^\s*/.exec(lines[j])[0].length;
if (lead <= indent) break;
body.push(lines[j]);
}
out.push({ line: i + 2, text: body.join('\n') });
i = j - 1;
}
return out;
}
/** Jobs of a workflow file, as {id, line, lines} — `jobs:` mapping, one level in. */
function jobs(lines) {
const start = lines.findIndex((l) => /^jobs:\s*$/.test(l));
if (start < 0) return [];
const found = [];
for (let i = start + 1; i < lines.length; i++) {
const m = /^ {2}([A-Za-z0-9_-]+):\s*$/.exec(lines[i]);
if (m) found.push({ id: m[1], line: i + 1, at: i });
}
return found.map((job, k) => ({
...job,
lines: lines.slice(job.at, k + 1 < found.length ? found[k + 1].at : lines.length),
}));
}
/** Line index within a job at which the setup action has run, or -1. */
function setupAt(jobLines) {
for (let i = 0; i < jobLines.length; i++) {
if (!new RegExp(`uses:\\s*${SETUP.replace(/[.\\/]/g, '\\$&')}\\s*$`).test(jobLines[i])) continue;
// `install: 'false'` sets the toolchain up without a node_modules.
const withBlock = jobLines.slice(i + 1, i + 8).join('\n');
if (/^\s*install:\s*['"]?false['"]?\s*$/m.test(withBlock)) continue;
return i;
}
return -1;
}
/** True if a `defaults:` block in these lines names a shell. */
const declaresShell = (lines) => {
const at = lines.findIndex((l) => /^\s*defaults:\s*$/.test(l));
return at >= 0 && lines.slice(at + 1, at + 6).some((l) => /^\s+shell:\s*\S/.test(l));
};
/** True if the job this run script belongs to may run on a windows runner. */
function onWindows(jobLines) {
const runsOn = jobLines.find((l) => /^\s+runs-on:/.test(l)) ?? '';
if (/windows/.test(runsOn)) return true;
// A matrix runner: the strategy decides, so any windows entry counts.
return /\$\{\{/.test(runsOn) && jobLines.some((l) => /windows-(latest|\d)/.test(l));
}
/** True if the step containing the run script at `at` declares its own shell. */
function stepDeclaresShell(jobLines, at) {
let start = at;
while (start > 0 && !/^\s*-\s/.test(jobLines[start])) start -= 1;
const indent = /^\s*/.exec(jobLines[start])[0].length;
let end = start + 1;
while (end < jobLines.length && !(new RegExp(`^\\s{${indent}}-\\s`).test(jobLines[end]))) end += 1;
return jobLines.slice(start, end).some((l) => /^\s+shell:\s*\S/.test(l));
}
// POSIX-only spellings. PowerShell — the windows default — writes an environment
// variable as `$env:NAME`, so a bare `$NAME` there reads an undefined variable and
// the step neither fails nor does what it says; `[` it does not have at all.
const POSIX_ENV = /(?<!\$\{\{[^}]*)\$[A-Z][A-Z0-9_]{2,}|^\s*(if|elif|while)\s+\[|\[\[\s/m;
const violations = [];
const shellViolations = [];
/**
* Upload steps whose `path` runs through a dot-directory or names a dot-file without
* `include-hidden-files: true`. upload-artifact skips hidden paths by default and only
* WARNS that it found nothing, so the step passes and the artifact never exists — the
* parity frames a golden failure is meant to hand over went missing exactly that way.
*/
function hiddenUploads(lines) {
const out = [];
for (let i = 0; i < lines.length; i++) {
if (!/^\s*(?:-\s+)?uses:\s*actions\/upload-artifact@/.test(lines[i])) continue;
let start = i;
while (start > 0 && !/^\s*-\s/.test(lines[start])) start--;
const dash = /^\s*/.exec(lines[start])[0].length;
let end = start + 1;
while (end < lines.length && (lines[end].trim() === ''
|| /^\s*/.exec(lines[end])[0].length > dash)) end++;
const step = lines.slice(start, end);
if (step.some((l) => /^\s*include-hidden-files:\s*true\s*$/.test(l))) continue;
const paths = [];
const at = step.findIndex((l) => /^\s*path:/.test(l));
if (at < 0) continue;
const inline = /^\s*path:\s*(.*)$/.exec(step[at])[1].trim();
if (inline && !/^[|>]/.test(inline)) paths.push(inline);
else {
const indent = /^\s*/.exec(step[at])[0].length;
for (let k = at + 1; k < step.length && /^\s*/.exec(step[k])[0].length > indent; k++) {
if (step[k].trim()) paths.push(step[k].trim());
}
}
const hidden = paths.filter((p) => !p.includes('${{')
&& p.split('/').some((seg) => /^\.[^./]/.test(seg)));
if (hidden.length > 0) out.push({ line: i + 1, paths: hidden });
}
return out;
}
const hiddenUploadViolations = [];
for (const file of readdirSync(WORKFLOWS).filter((f) => /\.ya?ml$/.test(f))) {
const lines = readFileSync(path.join(WORKFLOWS, file), 'utf8').split(/\r?\n/);
for (const v of hiddenUploads(lines)) hiddenUploadViolations.push({ file, ...v });
const found = jobs(lines);
const jobsAt = lines.findIndex((l) => /^jobs:\s*$/.test(l));
const workflowShell = declaresShell(lines.slice(0, jobsAt < 0 ? lines.length : jobsAt));
// A workflow with no jobs is not a workflow — it means the scan above stopped
// understanding the file, and a checker that reads nothing passes everything.
if (found.length === 0) {
console.error(`✗ .github/workflows/${file}: no jobs found — this check cannot read it`);
process.exit(1);
}
for (const job of found) {
const installed = setupAt(job.lines);
const shellSettled = workflowShell || declaresShell(job.lines);
const windows = onWindows(job.lines);
for (const script of runScripts(job.lines)) {
if (windows && !shellSettled && POSIX_ENV.test(script.text)
&& !stepDeclaresShell(job.lines, script.line - 1)) {
shellViolations.push({
file,
line: job.line + script.line - 1,
job: job.id,
what: (script.text.split('\n').find((l) => POSIX_ENV.test(l)) ?? script.text).trim(),
});
}
const cmd = NEEDS_INSTALL.find((re) => re.test(script.text));
if (!cmd) continue;
if (installed >= 0 && installed < script.line - 1) continue;
const body = script.text.split('\n');
const offset = body.findIndex((l) => cmd.test(l));
violations.push({
file,
line: job.line + script.line - 1 + Math.max(offset, 0),
job: job.id,
what: (body[offset] ?? script.text).trim(),
why: installed < 0 ? `job "${job.id}" never runs ${SETUP}` : `${SETUP} runs after this step`,
});
}
}
}
// The gate list is one list only while both scopes read it. A workflow that
// enumerates check-*.mjs steps of its own is the second list growing back.
const gateProblems = [];
for (const g of GATES) {
if (g.where === undefined) continue;
if (!SCOPES.includes(g.where)) gateProblems.push(`gate "${g.id}" has scope "${g.where}" (have: ${SCOPES.join(', ')})`);
if (!(typeof g.why === 'string' && g.why.trim())) {
gateProblems.push(`gate "${g.id}" runs in ${g.where} only, with no reason — say why the other scope cannot`);
}
}
const ciYml = readFileSync(path.join(WORKFLOWS, 'build.yml'), 'utf8');
if (!ciYml.includes('run-gates.mjs')) {
gateProblems.push('build.yml does not run tools/run-gates.mjs — CI would be back to a gate list of its own');
}
for (const g of GATES) {
const own = g.run.match(/tools\/(check-[\w-]+\.mjs)/);
if (own && ciYml.includes(own[1]) && g.where !== 'local') {
gateProblems.push(`build.yml names ${own[1]} directly; run-gates already runs it for the ci scope`);
}
}
if (gateProblems.length > 0) {
console.error('\n✗ the static gate list does not hold up:\n');
for (const p of gateProblems) console.error(` ${p}`);
process.exit(1);
}
if (hiddenUploadViolations.length > 0) {
console.error(`\n✗ ${hiddenUploadViolations.length} artifact upload(s) name a hidden path and would upload nothing:\n`);
for (const v of hiddenUploadViolations) {
console.error(` ${path.join('.github/workflows', v.file)}:${v.line} ${v.paths.join(', ')}`);
}
console.error('\nAdd `include-hidden-files: true` to the step: upload-artifact skips dot-paths');
console.error('by default and only warns, so the artifact is simply never there.\n');
process.exit(1);
}
if (shellViolations.length > 0) {
console.error(`\n✗ ${shellViolations.length} step(s) that can run on windows use POSIX shell without saying so:\n`);
for (const v of shellViolations) {
console.error(` ${path.join('.github/workflows', v.file)}:${v.line} ${v.what}`);
console.error(` job "${v.job}" can run on windows, where the default shell is PowerShell\n`);
}
console.error('Add `shell: bash` to the step, or a `defaults: run: shell: bash` block.');
console.error('It already cost a release pipeline once: the pin step wrote nothing and');
console.error('the cache restore failed asking for a key it was never given.\n');
process.exit(1);
}
/**
* The two packaging legs of a release sign by ONE mechanism. Gated to a tag push,
* the keychain stood up for only one of them and the other took the .p12 through
* CSC_LINK — so the rehearsal rehearsed what the release does not do.
*/
const RELEASE_WF = 'release-desktop.yml';
const signing = [];
if (existsSync(path.join(WORKFLOWS, RELEASE_WF))) {
// Newlines are read as \r?\n: a Windows checkout carries CRLF, and a rule that
// cannot see the step reports it MISSING — the loudest way to be wrong.
const text = readFileSync(path.join(WORKFLOWS, RELEASE_WF), 'utf8');
const keychain = /- name: Stand up the signing keychain\r?\n\s+if: ([^\r\n]+)/.exec(text);
if (!keychain) {
signing.push('no "Stand up the signing keychain" step — the signing mechanism cannot be located');
} else if (/event_name/.test(keychain[1])) {
signing.push(`the signing keychain is gated on the event (${keychain[1].trim()}) — then one`
+ ' packaging leg signs by another mechanism, and it is the leg nobody runs');
}
for (const m of text.matchAll(/^\s+CSC_LINK:/gm)) {
signing.push(`CSC_LINK is declared at character ${m.index} — neither leg may: macOS signs out`
+ ' of the keychain, and on Windows it would sign the installer with an Apple certificate');
}
}
if (signing.length > 0) {
console.error(`\n✗ the release's two packaging legs do not sign the same way:\n`);
for (const v of signing) console.error(` ${RELEASE_WF}: ${v}`);
console.error('\nA dry run is a rehearsal only if it rehearses what the release does.\n');
process.exit(1);
}
if (violations.length > 0) {
console.error(`\n✗ ${violations.length} workflow step(s) run workspace tooling with no install:\n`);
for (const v of violations) {
console.error(` ${path.join('.github/workflows', v.file)}:${v.line} ${v.what}`);
console.error(` ${v.why}\n`);
}
console.error(`Add \`- uses: ${SETUP}\` to the job before the step. It is where the`);
console.error('toolchain versions live, and it installs the workspace frozen.\n');
process.exit(1);
}
console.log('✓ every workflow step that runs workspace tooling installs it first');
console.log('✓ every windows-capable step that speaks POSIX shell says which shell it wants');
console.log('✓ every artifact upload from a hidden path says it includes hidden files');
console.log(`✓ ${GATES.length} static gate(s) in one list; CI runs it through run-gates.mjs`);
console.log('✓ the release\'s dry run signs by the same mechanism its publish does');