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.

15.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  check-golden.mjs — the certification corpus says what it covers, or says why not.
 *
 * The Golden Project Suite is an argument that a release ships working games. An
 * argument with a silent hole in it is worse than no argument: "the suite is
 * green" then means "the suite is green about the things it happens to run".
 *
 * So every capability the suite claims must have a project behind it, every
 * project must exist and be packageable, and every target must be a real export
 * target. A capability nothing covers is allowed — declared in KNOWN_GAPS, with
 * a reason, so the hole is a sentence somebody wrote.
 */
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import path from 'node:path';
import {
  GOLDEN, CAPABILITIES, KNOWN_GAPS, EVIDENCE, TIERS, TARGETS,
  SHIPPED, CENSUS_FLOOR, shippedGround, EVIDENCE_FORMATS, NOT_EVIDENCE_FORMATS,
  atTier, uncoveredCapabilities, nonGoldenExamples, projectDir, parityFor, interactFor,
  ROOT,
} from './goldenProjects.mjs';
import { CRITERIA } from './releaseGate.mjs';

const problems = [];
const fail = (msg) => problems.push(msg);

/** What a project is, as text: its sources plus the scene and prefab data it
 *  opens, since a capability can be exercised declaratively. */
const projectTextCache = new Map();
/** Every extension the reader met, so it can be held to classifying them. */
const seenFormats = new Set();
function projectText(id) {
  if (projectTextCache.has(id)) return projectTextCache.get(id);
  const parts = [];
  const walk = (dir) => {
    let entries;
    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
    for (const e of entries) {
      if (e.name === '.esengine' || e.name === 'node_modules' || e.name === 'dist') continue;
      const p = path.join(dir, e.name);
      if (e.isDirectory()) walk(p);
      else {
        const ext = e.name.slice(e.name.lastIndexOf('.'));
        seenFormats.add(ext);
        if (EVIDENCE_FORMATS.includes(ext)) {
          try { parts.push(readFileSync(p, 'utf8')); } catch { /* unreadable */ }
        }
      }
    }
  };
  walk(projectDir(id));
  const text = parts.join('\n');
  projectTextCache.set(id, text);
  return text;
}

/** Capabilities a packaged frame cannot show, and the declaration whose run reads them. */
const NEEDS_RUN = {
  'texture-atlas': 'atlas',
  audio: 'audio',
  'authored-sound': 'authoredAudio',
  settings: 'settings',
  'safe-area': 'safeArea',
  'pause-resume': 'suspend',
  'hot-update': 'runBy',
  rollback: 'runBy',
  // A frame of two coloured squares is what a working session and a broken one
  // both look like. Nothing about replication is visible in a screenshot, so the
  // claim needs the run that opens a socket.
  networking: 'runBy',
  // A packaged frame looks the same whether the first sight of something cost a
  // compile or not. Only a run that watches the frame it first appears on says.
  'shader-readiness': 'runBy',
};

/** Commands a release is defined as running — what makes `runBy` more than a string. */
const SCHEDULED = CRITERIA.map((c) => c.answeredBy ?? '').join('\n');

// 1. Every golden id is a project that exists and declares a scene to open.
const seen = new Set();
// The engine's own list of targets, so a platform it gained cannot be one no
// golden project is allowed to name — which is how Douyin shipped as a built-in
// target while this file would have rejected a project that certified it.
{
  const src = readFileSync(path.join(ROOT, 'pipeline', 'src', 'project', 'platforms.ts'), 'utf8');
  const block = /BUILTIN_PLATFORMS: readonly BuiltinPlatform\[\] = \[([\s\S]*?)\];/.exec(src);
  if (!block) fail('no BUILTIN_PLATFORMS in pipeline/src/project/platforms.ts — the list moved');
  else {
    const engine = [...block[1].matchAll(/'([a-z0-9]+)'/g)].map(([, p]) => p);
    const missing = engine.filter((p) => !TARGETS.includes(p));
    if (missing.length) {
      fail(`the engine builds ${missing.join(', ')}, which no golden project may name — add to TARGETS`);
    }
  }
}

for (const g of GOLDEN) {
  if (seen.has(g.id)) fail(`"${g.id}" is listed twice`);
  seen.add(g.id);

  const manifest = path.join(projectDir(g.id), 'project.esproject');
  if (!existsSync(manifest)) {
    fail(`"${g.id}" has no examples/${g.id}/project.esproject — a golden project must be packageable`);
    continue;
  }
  let parsed;
  try {
    parsed = JSON.parse(readFileSync(manifest, 'utf8'));
  } catch (e) {
    fail(`"${g.id}" has an unreadable manifest: ${e.message}`);
    continue;
  }
  // Every stage after "open" needs a scene to open; an export with no entry
  // scene packages an empty game and still exits 0.
  const scene = parsed.defaultScene;
  if (!scene) fail(`"${g.id}" declares no defaultScene — the chain has nothing to open`);
  else if (!existsSync(path.join(projectDir(g.id), scene))) {
    fail(`"${g.id}" names a defaultScene that is not there: ${scene}`);
  }

  if (!TIERS.includes(g.tier)) fail(`"${g.id}" has tier "${g.tier}" (have: ${TIERS.join(', ')})`);
  if (!g.targets?.length) fail(`"${g.id}" names no targets — then nothing packages it`);
  for (const t of g.targets ?? []) {
    if (!TARGETS.includes(t)) fail(`"${g.id}" names target "${t}" (have: ${TARGETS.join(', ')})`);
  }
  // Parity is the release's own claim, so opting out of it is a sentence, not a flag.
  if (g.parityGap !== undefined && !(typeof g.parityGap === 'string' && g.parityGap.trim())) {
    fail(`"${g.id}" sets parityGap without a reason — say why its frames cannot be compared`);
  }
  if (g.parity !== undefined && !(typeof g.parity === 'number' && g.parity > 0 && g.parity < 1)) {
    fail(`"${g.id}" has parity ${g.parity} — expected a tolerance between 0 and 1`);
  }
  if (g.parity !== undefined && g.parityGap) fail(`"${g.id}" both sets a parity tolerance and opts out`);
  // Same bargain as parity: a project that cannot be driven says why.
  if (g.interactGap !== undefined && !(typeof g.interactGap === 'string' && g.interactGap.trim())) {
    fail(`"${g.id}" sets interactGap without a reason — say why nothing can be pressed`);
  }
  if (g.interact && g.interactGap) fail(`"${g.id}" both declares input and opts out of it`);
  if (!g.interact && !g.interactGap) {
    fail(`"${g.id}" neither declares input nor says why it has none — the chain has no interact step for it`);
  }
  if (g.interact && !(g.interact.keys?.length > 0) && !g.interact.pointer) {
    fail(`"${g.id}" declares input with neither keys nor a pointer target`);
  }
  const pt = g.interact?.pointer;
  if (pt && !(pt.x >= 0 && pt.x <= 1 && pt.y >= 0 && pt.y <= 1)) {
    fail(`"${g.id}" has a pointer target outside the surface — x/y are fractions, not pixels`);
  }
  if (!g.certifies?.length) fail(`"${g.id}" certifies nothing — say what it is in the suite for`);
  for (const c of g.certifies ?? []) {
    if (!CAPABILITIES.includes(c)) fail(`"${g.id}" certifies "${c}", which is not a declared capability`);
    // Packaging and parity come free with being in the corpus; these do not.
    // Claiming one without declaring the run that reads it is how a capability
    // ends up "covered" by a project that never exercises it.
    const block = NEEDS_RUN[c];
    if (block && !g[block]) {
      fail(`"${g.id}" certifies "${c}" but declares no ${block} — a claim only a run can settle needs that run`);
    }
    // The claim has to be findable in the project. Without this, certifying a
    // capability is a word in a registry: space-shooter certified `audio` and had
    // no sound in it, and the coverage check below was satisfied by that.
    if (!(c in EVIDENCE)) {
      fail(`"${c}" has no EVIDENCE pattern — say what exercising it looks like, or null if nothing can`);
    } else if (EVIDENCE[c] && !EVIDENCE[c].test(projectText(g.id))) {
      fail(`"${g.id}" certifies "${c}" but nothing in the project matches ${EVIDENCE[c]} — the claim is not backed`);
    }
  }
  // A command nobody schedules is the hole this whole file exists to refuse: the
  // hot-update run existed for a year and no criterion or workflow ever ran it.
  if (g.runBy && !SCHEDULED.includes(g.runBy)) {
    fail(`"${g.id}" is settled by \`${g.runBy}\`, which no release criterion runs — add it to releaseGate.mjs`);
  }
  // Membership is only coverage while it is declared somewhere: moving those
  // textures out, or dropping the atlases entry, would take the claim with them.
  if (g.atlas) {
    if (!(g.atlas.packed > 0)) fail(`"${g.id}" declares atlas without a positive packed count`);
    const assets = path.join(projectDir(g.id), 'assets');
    const byFolder = existsSync(assets)
      && readdirSync(assets, { withFileTypes: true, recursive: true })
        .some((e) => e.isDirectory() && e.name.endsWith('.atlas'));
    let declared = false;
    try {
      const cfg = JSON.parse(readFileSync(path.join(projectDir(g.id), '.esengine', 'asset-groups.json'), 'utf8'));
      declared = Object.keys(cfg.atlases ?? {}).length > 0;
    } catch { declared = false; }
    if (!byFolder && !declared) {
      fail(`"${g.id}" claims texture-atlas with no atlas: no <name>.atlas/ folder and no \`atlases\` entry`);
    }
  }
  // The fixture is only a guard while it is still there AND still odd-sized.
  if (g.oddSizedKtx2) {
    const abs = path.join(projectDir(g.id), g.oddSizedKtx2);
    if (!existsSync(abs)) fail(`"${g.id}" names oddSizedKtx2 ${g.oddSizedKtx2}, which is not there`);
    else {
      // KTX2 header: 12-byte identifier, vkFormat, typeSize, then width, height.
      const head = readFileSync(abs).subarray(0, 28);
      const w = head.readUInt32LE(20);
      const h = head.readUInt32LE(24);
      if (w % 4 === 0 && h % 4 === 0) {
        fail(`"${g.id}" names oddSizedKtx2 ${g.oddSizedKtx2}, but ${w}x${h} IS whole blocks — it guards nothing`);
      }
    }
  }
  const au = g.audio;
  if (au) {
    const t = au.toggle;
    if (!t || !(t.x >= 0 && t.x <= 1 && t.y >= 0 && t.y <= 1)) {
      fail(`"${g.id}" declares audio without a toggle inside the surface — x/y are fractions`);
    }
    if (!au.bar) fail(`"${g.id}" declares audio without a bar to read — then nothing says signal arrived`);
    // A floor of 0 would pass on a bar the layout never sized, which is the same
    // reading as silence.
    if (!(au.floor > 0)) fail(`"${g.id}" declares audio with floor ${au.floor} — the silent height has to be a real one`);
  }

  const sa = g.safeArea;
  if (sa) {
    if (!sa.entity || !sa.reference) fail(`"${g.id}" declares safeArea without both an entity and a reference`);
    if (sa.entity === sa.reference) fail(`"${g.id}" reads safeArea against itself — the reference must be a second node`);
    // Equal insets would let a run that moves the node by one fixed amount pass.
    if (!(sa.top > 0) || !(sa.left > 0)) fail(`"${g.id}" declares safeArea without a positive top and left inset`);
    else if (sa.top === sa.left) fail(`"${g.id}" gives safeArea the same inset on both edges — then the run cannot see scaling`);
  }
}

// 2. No capability is claimed by the suite and covered by nobody.
// Every shipped feature is classified, and every classification names one.
// CAPABILITIES is otherwise the only author of how big the world is, and a list
// answerable only against itself reports full coverage of whatever it contains.
const ground = shippedGround();
const matched = new Map();
for (const bullet of ground) {
  const keys = Object.keys(SHIPPED).filter((k) => bullet.headline.startsWith(k));
  if (keys.length === 0) {
    fail(`${bullet.version} ships "${bullet.headline.slice(0, 60)}…" and nothing classifies it`
      + ' — name the capability a project must carry, or why none can');
  } else if (keys.length > 1) {
    fail(`${bullet.version} "${bullet.headline.slice(0, 40)}…" is classified ${keys.length} times`
      + ` (${keys.join(' / ')}) — one shipped feature, one classification`);
  } else {
    matched.set(keys[0], (matched.get(keys[0]) ?? 0) + 1);
  }
}
for (const [key, entry] of Object.entries(SHIPPED)) {
  // The other direction: a classification naming no feature is a census that has
  // stopped reading the thing it censuses.
  if (!matched.has(key)) {
    fail(`nothing at or after ${CENSUS_FLOOR} ships "${key}" — the classification names no feature`);
  }
  const certifies = entry.certifies === undefined ? [] : [entry.certifies].flat();
  if (certifies.length === 0 && !entry.notCertifiable) {
    fail(`"${key}" is classified as neither certifiable nor not — say which`);
  }
  for (const c of certifies) {
    if (!CAPABILITIES.includes(c)) {
      fail(`"${key}" says a project must certify "${c}", which is not a declared capability`);
    }
  }
}

// Every format a golden project holds is either evidence or declared not to be.
// A reader that opens some of a project answers about all of it: root motion and
// clip events were authored, verified on the packaged game, and read by nothing.
for (const g of GOLDEN) projectText(g.id);
for (const ext of [...seenFormats].sort()) {
  if (EVIDENCE_FORMATS.includes(ext) || ext in NOT_EVIDENCE_FORMATS) continue;
  fail(`golden projects hold "${ext}" files and the evidence reader classifies it as neither`
    + ' read nor irrelevant — say which, or a capability authored in one reads as absent');
}
for (const ext of EVIDENCE_FORMATS) {
  if (ext in NOT_EVIDENCE_FORMATS) fail(`"${ext}" is declared both evidence and not`);
}

for (const c of uncoveredCapabilities()) {
  fail(`nothing certifies "${c}" — add a project, or declare the gap in KNOWN_GAPS with a reason`);
}

// 3. A declared gap that something now covers is stale bookkeeping.
const covered = new Set(GOLDEN.flatMap((g) => g.certifies));
for (const c of Object.keys(KNOWN_GAPS)) {
  if (!CAPABILITIES.includes(c)) fail(`KNOWN_GAPS names "${c}", which is not a declared capability`);
  else if (covered.has(c)) fail(`"${c}" is declared a gap but ${[...covered].includes(c) ? 'a project certifies it' : ''} — drop the entry`);
}

// 4. Every tier can actually run something.
for (const tier of TIERS) {
  if (atTier(tier).length === 0) fail(`tier "${tier}" selects no projects`);
}

if (problems.length) {
  console.error('check-golden: the certification corpus does not hold up.\n');
  for (const p of problems) console.error(`  ${p}`);
  process.exit(1);
}

const noParity = GOLDEN.filter((g) => parityFor(g) === null);
const driven = GOLDEN.filter((g) => interactFor(g) !== null);
const gaps = Object.keys(KNOWN_GAPS).length;
const pairs = TIERS.map((t) => `${t} ${atTier(t).length}`).join(' / ');
console.log(
  `check-golden: ${GOLDEN.length} golden project(s) certify ${covered.size}/${CAPABILITIES.length} capabilities`
  + `, ${ground.length} shipped feature(s) classified since ${CENSUS_FLOOR}`
  + ' (release notes are the ground; nothing gates THEIR completeness)'
  + `, ${gaps} declared gap(s) — ok (${pairs})`,
);
console.log(`  evidence read from ${EVIDENCE_FORMATS.length} authored format(s);`
  + ` ${Object.keys(NOT_EVIDENCE_FORMATS).length} more carry no claim;`
  + ` ${seenFormats.size} met in the corpus, 0 unclassified`);
// Named, not counted. A number is a hole nobody reads; the whole bargain of
// declaring one is that it stays in front of the next person to run this.
for (const [c, why] of Object.entries(KNOWN_GAPS)) {
  console.log(`  no project certifies "${c}" — ${why}`);
}
console.log(`  ${driven.length} project(s) drive their package with input; ${GOLDEN.length - driven.length} say why they cannot`);
for (const g of noParity) console.log(`  no editor/package comparison for ${g.id}: ${g.parityGap}`);
const rest = nonGoldenExamples();
if (rest.length) console.log(`  ${rest.length} example(s) outside the corpus (smoke-tested, not certified)`);