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 gates.mjs — the static gates, in order, and where each one runs.
*
* There were two lists again. `pnpm run verify` held eighteen gates and CI's
* Tests job held six, overlapping in one. So seventeen gates never ran in CI and
* five never ran locally — which is how a local run went green and CI failed on
* check-examples.
*
* One ordered list, then, with `where` saying which scope pays for each. Order
* is load-bearing: the declaration checks and the example type-check both read
* what `sdk-build` emits.
*/
/** Scopes a gate can run in. `both` is the default and needs no excuse. */
export const SCOPES = ['local', 'ci'];
/**
* `run` is a shell command from the repo root. `where` narrows a gate to one
* scope and then owes a `why` — a gate that quietly runs in one place is the
* thing this file exists to stop.
*
* `needs: 'editor'` marks a gate whose SUBJECT is the editor. The editor is an
* optional submodule, so those cannot run in a checkout without one — and a
* skipped gate has to say so, since silence there reads as a clean bill.
*
* `covers` names the test directories a gate actually runs, which is what makes
* "the full gate suite is green" mean something: check-verification-authority
* compares the claim against the directories that HOLD tests, so a suite nothing
* invokes is a finding rather than a silence.
*
* `covers` is also the COST dimension: `--suites none` drops exactly the gates
* that run a suite — orthogonal to `where`, which says a gate CANNOT run here.
* `owns` is the other half: the SOURCE a suite answers for, and `--suites owed`
* runs the ones a change touched, so it meets its unit-test owner before the remote.
*/
export const GATES = [
// `exclusive: true` is a build or a writer of what a later gate reads: a `--jobs` run cuts the list there and runs it alone.
{ id: 'tsc-sdk', run: 'pnpm --filter ./sdk exec tsc --noEmit' },
// Up here rather than beside `tsc-pipeline`: the compiler resolves `esengine`
// to its own stub (compiler/tsconfig.json), so it needs nothing built and has
// no reason to wait for `sdk-build`.
{ id: 'tsc-compiler', run: 'pnpm --filter @estella/compiler exec tsc --noEmit -p tsconfig.json' },
{ id: 'gl-boundary', run: 'node tools/check-gl-boundary.mjs' },
{ id: 'draw-command-boundary', run: 'node tools/check-draw-command-boundary.mjs' },
{ id: 'shadow-pass', run: 'node tools/check-shadow-pass.mjs' },
{ id: 'frame-lifecycle', run: 'node tools/check-frame-lifecycle.mjs' },
{ id: 'postfx-aa', run: 'node tools/check-postfx-aa.mjs' },
{ id: 'sidemodule-gates', run: 'node tools/check-sidemodule-gates.mjs' },
{ id: 'engine-exports', run: 'node tools/check-engine-exports.mjs' },
{ id: 'fixture-scenes', run: 'node tools/check-fixture-scenes.mjs' },
{ id: 'prefab-overrides', run: 'node tools/check-prefab-overrides.mjs' },
{ id: 'doc-imports', run: 'node tools/check-doc-imports.mjs' },
{ id: 'doc-sources', run: 'node tools/check-doc-sources.mjs' },
{ id: 'architecture-doc', run: 'node tools/check-architecture-doc.mjs' },
{ id: 'native-bindings', run: 'node tools/check-native-bindings.mjs' },
// The generator's output is checked in, so its authority and its artifact can
// disagree with nothing between them to notice.
{ id: 'generated-fresh', run: 'node tools/check-generated-fresh.mjs' },
// The generator's own cases had no runner at all — the file said how to run it
// and nothing did, which is the shape check-verifier-owners exists to refuse.
{ id: 'eht-validation', run: 'python3 tools/eht/test_validation.py' },
{ id: 'transform-seam', run: 'node tools/check-transform-seam.mjs' },
// …and the other direction: every C++ writer of a composition input is a
// seam somebody classified, rather than a count that moves with a refactor.
{ id: 'transform-writers', run: 'node tools/census-transform-writers.mjs --gate' },
{ id: 'api-surface', run: 'node tools/api-surface.mjs --check' },
// Reads the snapshot the gate above just proved current, against the one the
// last release tag shipped — drift says the surface moved, this says a promise did.
{ id: 'api-surface-baseline', run: 'node tools/api-surface.mjs --check-baseline' },
{ id: 'freeze-bar', run: 'node tools/check-freeze-bar.mjs' },
{ id: 'tier-leaks', run: 'node tools/check-tier-leaks.mjs' },
// The three above ask what the surface IS. This asks what it is missing: a
// subsystem whose plugin reaches no entry is one the engine has and a game
// cannot add — which is what 3D physics was for four releases.
{ id: 'plugin-door', run: 'node tools/check-plugin-door.mjs' },
// A component tagged @beta whose Data interface is untagged promises the name
// and not the fields, which is no promise at all.
{ id: 'data-tiers', run: 'node tools/check-data-tiers.mjs' },
// The SDK's tiers are enforced by the three gates above. The editor plugin API
// has no snapshot to enforce, so what is enforced there is the ANSWER: that it
// is experimental, said the same way in every place someone reads it.
{ id: 'plugin-api-contract', run: 'node tools/check-plugin-api-contract.mjs' },
{ id: 'residency-authority', run: 'node tools/check-residency-authority.mjs' },
{ id: 'workspace-continuity', run: 'node tools/check-workspace-continuity.mjs' },
{ id: 'project-health', run: 'node tools/check-project-health.mjs' },
// Everything below reads what this emits: the declaration snapshot, the
// editor's own type-check and the examples all resolve `esengine` from dist.
{ id: 'sdk-build', exclusive: true, run: 'pnpm --filter ./sdk build' },
// A blank mini-game package carries none of a subsystem it does not use: the shared chunks are the union of every entry's code, and one unmarked
// top-level `new SomePlugin()` is how 84KB of terrain and water rode every package.
{ id: 'lean-bundle', run: 'node tools/check-lean-bundle.mjs' },
{ id: 'api-surface-dts', run: 'node tools/api-surface.mjs --check-dts' },
// Both read `esengine` from dist, and the editor reads the pipeline.
{ id: 'tsc-pipeline', run: 'pnpm --filter @estella/pipeline exec tsc --noEmit' },
// needs: 'editor' is load-bearing here rather than merely tidy: `pnpm --filter`
// prints "No projects matched the filters" and exits 0, so without a checkout
// this gate reported success having type-checked nothing at all.
{ id: 'tsc-editor', run: 'pnpm --filter @estella/editor exec tsc --noEmit', needs: 'editor' },
{ id: 'editor-tests', run: 'pnpm --filter @estella/editor test',
needs: 'editor', covers: ['desktop/tests'], owns: ['desktop'] },
// What type-checking cannot see: the renderer runs in a browser, so a module
// that reaches it with a node dependency throws before React mounts and takes
// the whole editor with it.
{ id: 'renderer-bundle', run: 'node tools/check-renderer-bundle.mjs', needs: 'editor' },
// The shipped plugins type-check against the editor's LIVE plugin API surface
// (types.ts, the file authors are handed), so a change to it that no plugin
// could survive fails here rather than in someone else's project.
{ id: 'tsc-plugins', run: 'pnpm -r --filter "./plugins/*" exec tsc --noEmit' },
{ id: 'plugin-tests', run: 'pnpm -r --filter "./plugins/*" test',
covers: ['plugins/audio-mixer/tests', 'plugins/ldtk/tests', 'plugins/minigame-services/tests'],
owns: ['plugins'] },
// The engine's own TS suites (pipeline + tooling). They lived in desktop/tests
// until the editor split, where a checkout without the editor ran none of them.
{ id: 'engine-tests', run: 'pnpm run test', covers: ['pipeline/tests', 'tools/tests'],
owns: ['pipeline', 'tools'],
related: { root: '.', run: 'pnpm exec vitest related --run --config vitest.engine.config.ts' } },
// The SDK's own suites. They were run by NOTHING until 2026-08-30: the gate
// list said 76/76 while four of them did not compile against the source they
// test, and only a hand-run vitest found it.
{ id: 'sdk-tests', run: 'pnpm --filter ./sdk test', covers: ['sdk/tests'], owns: ['sdk'],
related: { root: 'sdk', run: 'pnpm --filter ./sdk exec vitest related --run' } },
// The AOT compiler carries its own oracle: a real example system lowered to
// EIR must move a world exactly the way node moves it.
// It also compiles the emitted C and requires the same bytes back: natively
// with any C compiler, and as wasm where emsdk is unpacked. Without either it
// still passes and PRINTS that the differential did not run — read the log.
{ id: 'compiler-tests', run: 'pnpm --filter @estella/compiler test', covers: ['compiler/tests'],
// Components too: EngineDigest.generated.h is a digest over every one of their
// fields, written by a compiler test, and a field added without it leaves a
// packaged native game refusing its own AOT module.
owns: ['compiler', 'src/esengine/ecs/components'] },
// The plugins we ship prove the public API only if they are held to it.
{ id: 'plugin-boundary', run: 'node tools/check-plugin-boundary.mjs' },
// Same shape of rule, other direction: what builds a project may not need the
// process that edits one.
{ id: 'pipeline-boundary', run: 'node tools/check-pipeline-boundary.mjs' },
// And the boundary holds in practice: a real project packages from the command
// line with no editor built.
{ id: 'headless-export', exclusive: true, run: 'node tools/check-headless-export.mjs' },
// The 478 SDK test files were in no checker's scope: the production config
// compiles src/ and vitest strips types. A ratchet, not a demand for zero —
// except in the net suites, which are held to none.
{ id: 'sdk-test-types', run: 'node tools/check-sdk-test-types.mjs' },
// Every mini-game package carries the core runtime, so a subsystem the core
// imports is in every package whether the project uses it or not.
{ id: 'core-carries-options', run: 'node tools/check-core-carries-options.mjs' },
// …and the other half: an entry that forgets to install them ships an app whose
// Spine entities silently never animate.
{ id: 'entries-install-options', run: 'node tools/check-entries-install-options.mjs' },
// And the half no text probe can see: `sideEffects` lists FILES, so a prologue
// the bundler puts in an unlisted chunk is dropped while still sitting in dist.
{ id: 'entry-boots', run: 'node tools/check-entry-boots.mjs' },
{ id: 'dist-side-effect-chunks', run: 'node tools/check-dist-side-effect-chunks.mjs' },
// Replication applies its inbox in arrival order, so reliable+ordered is a
// correctness condition. This compiles the claim: a transport that does not
// make it cannot reach replication.
{ id: 'transport-contract', run: 'node tools/check-transport-contract.mjs' },
// The multiplayer half of that claim: an authority runs as a plain Node
// process over a real socket. Also the only check of two facts the editor's
// preview has no way to reach — no local player, and a connection that LEAVES.
{
id: 'arena-server',
run: 'node tools/check-arena-server.mjs',
where: 'local',
why: 'the server it starts runs the real engine wasm, and the fast CI lane builds none;'
+ ' the engine-coupled job runs it where the artifact is, under ESTELLA_REQUIRE_WASM',
},
// The starter a networked game begins from: the same facts, checked against the template itself so it cannot rot unseen.
{
id: 'online-3d-server',
run: 'node tools/check-arena-server.mjs --project templates/online-3d --bound 1450 --speed 340',
where: 'local',
why: 'it starts a server on the real engine wasm too; the engine-coupled job runs it',
},
{ id: 'cycles', run: 'node tools/check-cycles.mjs' },
{ id: 'layers', run: 'node tools/check-layers.mjs' },
// A system's parameters are what the schedule knows about it; the World
// escape hatch has to say what it reaches for or the schedule knows nothing.
{ id: 'system-access', run: 'node tools/check-system-access.mjs' },
{ id: 'project-settings', run: 'node tools/check-project-settings.mjs', needs: 'editor' },
// "The full gate suite is green" only means something if every suite is in it.
{ id: 'verification-authority', run: 'node tools/check-verification-authority.mjs' },
// ...and "this push ran the suites it owed" only means something if what each
// suite answers for is a claim that resolves.
{ id: 'suite-ownership', run: 'node tools/check-suite-ownership.mjs' },
{ id: 'workflows', run: 'node tools/check-workflows.mjs' },
{ id: 'tool-spawn', run: 'node tools/check-tool-spawn.mjs' },
{ id: 'tool-calls', run: 'node tools/check-tool-calls.mjs', needs: 'editor' },
{ id: 'capabilities', run: 'node tools/check-capabilities.mjs', needs: 'editor' },
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs', needs: 'editor' },
{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
{ id: 'animator-parameters', run: 'node tools/check-animator-parameters.mjs' },
{ id: 'health-authority', run: 'node tools/check-health-authority.mjs' },
// A field declares that it carries an asset in one place; everything that acts
// on live assets has to read THAT rather than keep a list of components beside it.
{ id: 'live-asset-rebind', run: 'node tools/check-live-asset-rebind.mjs' },
// A hot reload re-evaluates the project bundle against a World still alive, so
// every public `define*` door owes an answer about what its second evaluation
// addresses — resources and events answered wrong, and every system read null.
{ id: 'reload-identity', run: 'node tools/check-reload-identity.mjs' },
// A scene that unloads and a load that failed halfway own the same things;
// two implementations of giving them back is how one came to miss four steps.
{ id: 'scene-teardown', run: 'node tools/check-scene-teardown.mjs' },
// The subsystem that held all four retired shapes at once: a module-global
// asset cache, an ownerless texture, an "active runtime" pointer, and
// World-local state on a plugin object several Apps share.
{ id: 'tilemap-realm', run: 'node tools/check-tilemap-realm.mjs' },
// The five spine lifetime invariants, each with the judgment that proves it:
// what they replaced were teardown protocols, and a protocol comes back quietly.
// An offscreen preview is addressed by its handle, never entered: no current
// preview, no begin/end pair, and batches that own their bytes.
{ id: 'preview-ownership', run: 'node tools/check-preview-ownership.mjs' },
{ id: 'spine-lifetimes', run: 'node tools/check-spine-lifetimes.mjs' },
// The profiler's spine section renders the realm's report and computes none
// of it: one side measures a frame, or two of them disagree about it.
{ id: 'spine-panel', run: 'node tools/check-spine-panel.mjs', needs: 'editor' },
// …and that each of them can be reached on a device, where the registry is
// assembled from ptr accessors rather than from embind.
{ id: 'native-components', run: 'node tools/check-native-components.mjs' },
{ id: 'shader-conditionals', run: 'node tools/check-shader-conditionals.mjs' },
{ id: 'mesh-vocabulary', run: 'node tools/check-mesh-vocabulary.mjs' },
{ id: 'mesh-shader-inputs', run: 'node tools/check-mesh-shader-inputs.mjs' },
{ id: 'mesh-instance-record', run: 'node tools/check-mesh-instance-record.mjs' },
// …and that whoever mints one can say how it survives a device generation:
// recovery only ever holds a number, so the answer has to exist before it runs.
{ id: 'mesh-provenance', run: 'node tools/check-mesh-provenance.mjs' },
// Every `esengine/*` specifier the SDK publishes has one answer for a script
// inside a packaged native game, and a subpath never means the bare specifier.
{ id: 'native-script-modules', run: 'node tools/check-native-script-modules.mjs' },
// …and that a packaged game really receives them: the table above is a
// promise, this exports a project and reads what its scripts bind to.
{ id: 'native-subpath-imports', run: 'node tools/check-native-subpath-imports.mjs' },
{ id: 'shader-blocks', run: 'node tools/check-shader-blocks.mjs' },
{ id: 'wgsl-twin', run: 'node tools/check-wgsl-twin.mjs' },
{
// The twin's FRESHNESS, as opposed to its shape above: fifteen shaders reached
// master carrying a stamp older than their own GLSL.
id: 'wgsl-twin-fresh',
run: "if [ -f build/wasm/web/esengine.js ]; then "
+ "node tools/gen-shader-twins.mjs --check --derived fixtures/scenes examples; "
+ "else echo 'wgsl-twin-fresh: skipped — no built engine in build/wasm/web'; fi",
where: 'local',
why: 'the check cooks each shader to hash the ASSEMBLED GLSL, so it needs the built engine and skips a machine without one; the render CI job runs it where the binary is',
},
{ id: 'shader-literals', run: 'node tools/check-shader-literals.mjs' },
// The engine's copy of the text culling agrees with the TS one only while the cases file is what the TS gives.
{ id: 'retained-text-cases', run: 'node tools/gen-retained-text-cases.mjs --check' },
{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },
{ id: 'gizmo-coverage', run: 'node tools/check-gizmo-coverage.mjs', needs: 'editor' },
{ id: 'corpus-authoring', run: 'node tools/check-corpus-authoring.mjs' },
{
// A baked room in the corpus rots the moment the baker changes, and a stale
// atlas looks exactly like a correct one. Rebaking is deterministic, so what
// is committed can simply be compared to what a bake of it produces now.
id: 'corpus-bake',
run: 'node pipeline/bin/estella.mjs bake-scene'
+ ' examples/physics-3d/assets/scenes/main.esscene --check',
why: 'the bake reads the meshes the scene names, and takes about ten seconds',
},
{ id: 'asset-vocabulary', run: 'node tools/check-asset-vocabulary.mjs' },
{ id: 'asset-refs', run: 'node tools/check-asset-refs.mjs' },
{ id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },
{ id: 'shadow-plan', run: 'node tools/check-shadow-plan.mjs' },
{ id: 'light-cap', run: 'node tools/check-light-cap.mjs' },
{ id: 'hdr-format', run: 'node tools/check-hdr-format.mjs' },
{ id: 'texture-format', run: 'node tools/check-texture-format.mjs' },
{ id: 'decision-inventory', run: 'node tools/check-decision-inventory.mjs', needs: 'editor' },
{ id: 'mutator-parity', run: 'node tools/check-mutator-parity.mjs', needs: 'editor' },
{ id: 'version-authority', run: 'node tools/check-version-authority.mjs', needs: 'editor' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs', needs: 'editor' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },
{ id: 'key-codes', run: 'node tools/check-key-codes.mjs' },
{ id: 'theme', run: 'node tools/check-theme.mjs', needs: 'editor' },
// Its own gate rather than part of `theme`: the readers of the editor's
// variables are the editor, the plugins and the docs, and only the first is
// check-theme's subject.
{ id: 'css-vars', run: 'node tools/check-css-vars.mjs', needs: 'editor' },
// The specifiers a game writes against the SDK, held to what the package
// publishes: a map entry that resolves to nothing fails at load, not at build.
{ id: 'import-map', run: 'node tools/check-import-map.mjs' },
// The third-party tools a release carries are pinned to exact vendor files; a pin that is missing or malformed
// would only show on release day, when the files are built.
{ id: 'external-tools', run: 'node tools/sync-external-tools.mjs --check' },
// The exporter ships a web package by the chunk list the SDK build writes, so
// a list that disagrees with the emitted imports is a package missing a module.
{ id: 'sdk-chunk-manifest', run: 'node tools/check-sdk-chunk-manifest.mjs' },
// A packaging setting the manifest parser does not read is a setting that
// does nothing, in the editor and on a build server alike.
{ id: 'packaging-settings', run: 'node tools/check-packaging-settings.mjs' },
// A subsystem behind a subpath is paid for only by packages that import it,
// and one that should have and did not renders half a scene in silence.
{ id: 'subsystem-install-reach', run: 'node tools/check-subsystem-install-reach.mjs' },
// The generated entry is the only code that runs before the game, so the
// platform has to be installed there — not by a module side effect a bundler
// is free to drop, which is how every WeChat package stopped booting.
{ id: 'minigame-platform-install', run: 'node tools/check-minigame-platform-install.mjs' },
// A vendor claim that is wrong fails at upload or on a device, never at
// build: so each one cites the vendor or says what it is assumed from.
{ id: 'minigame-profile-claims', run: 'node tools/check-minigame-profile-claims.mjs' },
{ id: 'comment-style', run: 'node tools/check-comment-style.mjs' },
{ id: 'silent-writes', run: 'node tools/mutation-census.mjs --gate' },
{
id: 'cpp-tests', exclusive: true,
run: 'node tools/check-cpp-tests.mjs',
where: 'local',
why: 'it configures and builds a native cmake tree; CI compiles and RUNS those harnesses in its own C++ jobs',
},
{
id: 'native-build', exclusive: true,
run: 'node tools/check-native-build.mjs',
where: 'local',
why: 'it builds the engine out of the tree `cli native` configured; CI builds every native target from scratch',
},
{ id: 'verifier-exit', run: 'node tools/check-verifier-exit.mjs', needs: 'editor' },
{ id: 'render-scenes', run: 'node tools/check-render-scenes.mjs' },
{
id: 'gi-sdf-wgsl',
run: 'node tools/gi/check-sdf-wgsl.mjs',
where: 'local',
why: 'it runs the distance field trace on a WebGPU device against the closed-form distance to a sphere, and CI has no adapter',
},
{
id: 'gi-cost',
run: 'node tools/gi/check-gi-cost.mjs',
where: 'local',
why: 'it exports the GI lab and runs it on the machine GPU for the work counters of the dynamic GI; it says so and passes where there is no WebGPU adapter, and CI has none',
},
{ id: 'release-metadata', run: 'node tools/check-release-metadata.mjs' },
// A published desktop artifact has one name, declared, whitespace-free, and
// still distinct once the asset store has normalised it.
{ id: 'release-artifact-names', run: 'node tools/check-release-artifact-names.mjs', needs: 'editor' },
// …and that the updater feed a release publishes names files it carries. The
// gate runs the checker over fixtures; the release job runs it over the real
// asset list, which is the only place both halves exist at once.
{ id: 'release-manifest-refs', run: 'node tools/check-release-manifest-refs.mjs --assets tools/fixtures/release-assets.txt --manifests tools/fixtures/release-manifests' },
{ id: 'shipped-resources', run: 'node tools/check-shipped-resources.mjs', needs: 'editor' },
{ id: 'golden', run: 'node tools/check-golden.mjs' },
{
id: 'physics2d',
run: 'node tools/check-physics2d.mjs',
where: 'local',
why: 'it runs the built 2D physics wasm and skips a machine without one; the engine-coupled CI job runs it where the binary is, under ESTELLA_REQUIRE_WASM',
},
{
id: 'physics3d',
run: 'node tools/check-physics3d.mjs',
where: 'local',
why: 'it runs the built 3D physics wasm and skips a machine without one; the engine-coupled CI job runs it where the binary is, under ESTELLA_REQUIRE_WASM',
},
{
id: 'physics3d-physx',
run: 'node tools/check-physics3d-physx.mjs',
where: 'local',
why: 'it runs the built PhysX 3D wasm and skips a machine without one; the engine-coupled CI job runs it where the binary is, under ESTELLA_REQUIRE_WASM',
},
{ id: 'engine-gaps', run: 'node tools/check-engine-gaps.mjs' },
{ id: 'minigame-host', run: 'node tools/check-minigame-host.mjs' },
{ id: 'release-gate', run: 'node tools/check-release-gate.mjs' },
// release-gate says every criterion has something answering it; this says the
// other direction — every checker has something RUNNING it. `verify:aot` spent
// two releases broken because nothing did.
{ id: 'verifier-owners', run: 'node tools/check-verifier-owners.mjs' },
{ id: 'electron-preconditions', run: 'node tools/check-electron-preconditions.mjs' },
{ id: 'unanswered-exits', run: 'node tools/check-unanswered-exits.mjs' },
{ id: 'suite-preconditions', run: 'node tools/check-suite-preconditions.mjs' },
{ id: 'component-reference', run: 'node tools/component-reference.mjs --check' },
{ id: 'api-stability-page', run: 'node tools/api-stability.mjs --check' },
// The per-symbol tiers say what is frozen; this says what a creator can build
// on, and refuses a published verdict the tags do not carry.
{ id: 'subsystem-tiers', run: 'node tools/check-subsystem-tiers.mjs' },
// And whether the verdict was earned. subsystem-tiers holds the table against
// the tags; this holds a tier above experimental against the same evidence
// check-freeze-bar asks of a @public symbol.
{ id: 'tier-bar', run: 'node tools/check-tier-bar.mjs' },
// A TS enum that restates a C++ one crosses as a bare number: drift is not an
// error, it is a picture that is merely wrong. cpp-contract pins the ones
// somebody remembered; this says which ones nobody did.
{ id: 'enum-twins', run: 'node tools/check-enum-twins.mjs' },
// …and this says which facts nobody wrote down at all. A generated artifact no
// authority claims, or a cross-language pin no fact names, is a compatibility
// fact outside the compatibility system — the state EsEventOut was in.
{ id: 'contract-inventory', run: 'node tools/contract-inventory.mjs' },
// The two AOT roads share no code, so a step one grows and the other does not
// is invisible to a reader. Three were: events, commands, and the counter that
// exists to say a twin ran at all.
{ id: 'aot-duties', run: 'node tools/check-aot-duties.mjs' },
// Windows deletes asynchronously: the rmdir races the unlink it just did, and
// the temp tree a test made comes back ENOTEMPTY at random. Node's retry loop
// is right there and defaults to OFF.
{
id: 'script-failure',
run: 'node tools/check-script-failure.mjs',
where: 'local',
why: 'it BOOTS the package it builds, so it needs a real engine runtime and the fast CI'
+ ' lane builds none; the engine-coupled job runs it on the artifact',
},
{ id: 'screen-domain', run: 'node tools/check-screen-domain.mjs' },
{ id: 'rm-retries', run: 'node tools/check-rm-retries.mjs' },
{ id: 'examples', exclusive: true, run: 'node build-tools/cli.js check-examples' },
{ id: 'documents', exclusive: true, run: 'node build-tools/cli.js validate-documents' },
// The other half of release-metadata: metadata reads the CHANGELOG's shape, this reads whether anything shipped without reaching it. Three
// releases running lost features that only a hand-read of `git log` found.
// LAST on purpose. The list stops at its first red, and this one is red on any push whose user-facing commit has no note yet
// (12 of the last 13 CI runs): sitting in the middle it hid the 22 gates after it on every one of them. It reads only git history, so
// nothing after it depends on it, and nothing before it is hidden by it.
{ id: 'changelog-covers', run: 'node tools/check-changelog-covers.mjs', needs: 'editor' },
];
/** Whether `p` names, or sits under, one of `roots`. */
function under(p, roots) {
return roots.some((r) => p === r || p.startsWith(`${r}/`));
}
/**
* The suites `changed` owes — the direct unit-test owner of every path in it.
*
* A path no suite claims owes none: docs, examples and the C++ tree have owners
* of other kinds. Over-running is the safe direction here and under-running is
* the defect, so `owns` is declared at package granularity rather than per file.
*/
export function owedSuites(changed) {
const owed = new Set();
for (const g of GATES) {
if (g.owns && changed.some((p) => under(p, g.owns))) owed.add(g.id);
}
return owed;
}
/** The most changed files a suite is run in part for: past it the whole suite is the cheaper answer and the surer one. */
export const RELATED_MOST = 80;
/**
* How `gate` runs in part for `changed` (`--suites related`): its `related.run` handed the changed files under `related.root`, which
* runs the tests that import them. Null where the whole suite is owed: no `related`, a change that is not TypeScript source (a config,
* a fixture: anything may read those), a file that is gone, or more than RELATED_MOST. A test that reads a file without importing it
* is missed, so the run says which suites were run in part and CI runs every suite whole.
*/
export function relatedRun(gate, changed, exists = () => true) {
if (!gate.related || !gate.owns) return null;
const mine = changed.filter((p) => under(p, gate.owns));
if (mine.length === 0 || mine.length > RELATED_MOST) return null;
const root = gate.related.root === '.' ? '' : `${gate.related.root}/`;
const files = [];
for (const p of mine) {
if (!/\.(ts|tsx|mts)$/.test(p) || /(^|\/)[^/]*\.config\.[a-z]+$/.test(p) || !p.startsWith(root) || !exists(p)) return null;
files.push(p.slice(root.length));
}
return { run: `${gate.related.run} ${files.map((f) => `"${f}"`).join(' ')}`, files: files.length };
}
/**
* The gates a scope runs, in declaration order. `hasEditor` gates the editor
* ones; `suites` is 'all', 'none', or the set of suite ids a diff owes.
*/
export function gatesFor(scope, hasEditor = true, { suites = 'all' } = {}) {
if (!SCOPES.includes(scope)) throw new Error(`unknown scope "${scope}" (have: ${SCOPES.join(', ')})`);
return GATES.filter((g) => (!g.where || g.where === scope)
&& (hasEditor || g.needs !== 'editor')
&& (!g.covers?.length || suites === 'all' || (suites !== 'none' && suites.has(g.id))));
}