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.

3.3 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  api-stability.mjs — the tier inventory the docs publish, from the snapshots.
 *
 * A hand-written list of what is frozen is a second answer to a question
 * sdk/etc already answers, and the two would part company the first time
 * someone tagged a symbol without remembering the page. So the page is
 * generated from the snapshots and gated, the way the component reference is.
 *
 *   node tools/api-stability.mjs --check    exit 1 if the page is behind
 *   node tools/api-stability.mjs --update   regenerate it
 */
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { ROOT, ETC, ENTRIES } from './lib/sdkProgram.mjs';
import { parseSnapshot } from './lib/apiSnapshot.mjs';
import { SUBSYSTEMS } from './apiSubsystems.mjs';

const OUT = join(ROOT, 'docs/astro/src/data/apiStability.generated.json');

const mode = process.argv[2];
if (mode !== '--check' && mode !== '--update') {
    console.error('usage: node tools/api-stability.mjs --check | --update');
    process.exit(2);
}

/** Every symbol across every entry, unioned, with the entries it appears in. */
function inventory() {
    const symbols = new Map();
    for (const entryName of Object.keys(ENTRIES)) {
        const file = join(ETC, `${entryName}.api.md`);
        if (!existsSync(file)) continue;
        for (const [name, s] of parseSnapshot(readFileSync(file, 'utf8'))) {
            const seen = symbols.get(name);
            if (seen) { seen.entries.push(entryName); continue; }
            symbols.set(name, { name, kind: s.kind, tier: s.tier, deprecated: s.deprecated, entries: [entryName] });
        }
    }
    return symbols;
}

function build() {
    const symbols = [...inventory().values()];
    const of = (tier) => symbols
        .filter((s) => s.tier === tier)
        .sort((a, b) => (a.name < b.name ? -1 : 1))
        .map(({ name, kind, deprecated, entries }) => ({ name, kind, deprecated, entries }));

    const counts = { public: 0, beta: 0, experimental: 0, deprecated: 0 };
    for (const s of symbols) {
        if (counts[s.tier] !== undefined) counts[s.tier]++;
        if (s.deprecated) counts.deprecated++;
    }
    return JSON.stringify({
        note: 'Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.',
        counts,
        total: symbols.length,
        // The table a creator actually reads: check-subsystem-tiers holds each
        // verdict against the tags its entry symbols carry.
        subsystems: SUBSYSTEMS.map(({ id, title, titleZh, tier, why, whyZh, entry }) =>
            ({ id, title, titleZh, tier, why, whyZh, entry })),
        public: of('public'),
        beta: of('beta'),
    }, null, 2) + '\n';
}

const report = build();
if (mode === '--update') {
    writeFileSync(OUT, report);
    console.log(`wrote ${OUT}`);
    process.exit(0);
}

const existing = existsSync(OUT) ? readFileSync(OUT, 'utf8').replace(/\r\n?/g, '\n') : '';
if (existing !== report) {
    console.error('api-stability: the published tier inventory is behind sdk/etc.');
    console.error('Run: node tools/api-stability.mjs --update');
    process.exit(1);
}
console.log('api-stability: the published tier inventory matches the snapshots.');