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.

29.5 KB
Raw Blame
// 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))));
}