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.

14.1 KB
Raw Blame
// 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');