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.

26.6 KB
Raw Blame
#!/usr/bin/env node
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  api-surface.mjs — the SDK's public surface, snapshotted and governed.
 *
 * Every exported symbol's signature is snapshotted into sdk/etc/<entry>.api.md,
 * so a surface change is a reviewed diff rather than an accident.
 *
 * A declaration's release tag is the single authority for stability, and there
 * is no stable-by-default: an untagged symbol is @experimental, so freezing is
 * something a maintainer DOES rather than something they forget to prevent.
 *
 *   @public        frozen — 1.0 is expected not to break it
 *   @beta          may still adjust
 *   @experimental  no compatibility claim (the default)
 *   @internal      must not be exported from a public entry; on a MEMBER it is
 *                  allowed and marked, and carries no promise
 *
 *   --check          exit 1 on drift or policy violation
 *   --update         accept surface changes
 *   --check-dts      the built .d.ts still carries the documented surface
 *   --check-baseline the last release's @public promises still hold
 */

import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { join, relative } from 'node:path';
import { ROOT, SDK, ETC, ts, ENTRIES, createSdkProgram, leadingDoc } from './lib/sdkProgram.mjs';
import { TIERS, parseSnapshot, baselineFindings } from './lib/apiSnapshot.mjs';

const MODES = ['--check', '--update', '--check-dts', '--check-baseline'];
const mode = process.argv[2];
if (!MODES.includes(mode)) {
    console.error(`usage: node tools/api-surface.mjs ${MODES.join(' | ')}`);
    process.exit(2);
}

const errors = [];

// ---------------------------------------------------------------------------
// Baseline — what the last release promised, and whether it still holds
// ---------------------------------------------------------------------------

/**
 * The snapshots as of the last release tag. Git rather than a committed copy:
 * the tag is already the authority for what shipped, and a second copy would
 * need its own guard to stay honest.
 */
function baselineSnapshots(ref) {
    const out = new Map();
    for (const entryName of Object.keys(ENTRIES)) {
        const spec = `${ref}:sdk/etc/${entryName}.api.md`;
        try {
            const text = execFileSync('git', ['show', spec], {
                cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'],
            });
            out.set(entryName, parseSnapshot(text));
        } catch {
            // An entry that did not exist at the tag promised nothing.
        }
    }
    return out;
}

function lastReleaseRef() {
    const flag = process.argv.find((a) => a.startsWith('--baseline='));
    if (flag) return flag.slice('--baseline='.length);
    try {
        return execFileSync('git', ['describe', '--tags', '--abbrev=0', '--match', 'v[0-9]*'], {
            cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
        }).trim();
    } catch {
        return null;
    }
}

if (mode === '--check-baseline') {
    const ref = lastReleaseRef();
    if (!ref) {
        console.log('api-surface: no release tag to compare against — nothing was promised yet.');
        process.exit(0);
    }
    const baseline = baselineSnapshots(ref);
    let failed = 0;
    let claims = 0;
    for (const [entryName, was] of baseline) {
        const file = join(ETC, `${entryName}.api.md`);
        if (!existsSync(file)) continue;
        const now = parseSnapshot(readFileSync(file, 'utf8'));
        claims += [...was.values()].filter((s) => s.tier === 'public').length;
        const { failures, notes } = baselineFindings(was, now);
        for (const n of notes) console.log(`  note ${entryName}: ${n}`);
        if (!failures.length) continue;
        failed += failures.length;
        console.error(`BROKEN PROMISE: ${entryName} — ${ref} froze these and this tree does not keep them.`);
        for (const f of failures) console.error(`  ${f}`);
    }
    if (failed) {
        console.error(`\napi-surface: ${failed} broken promise(s) against ${ref}.`);
        console.error('Deprecate for a release before removing, or restore the signature.');
        process.exit(1);
    }
    console.log(`api-surface: ${claims} @public symbol(s) promised at ${ref}, all kept.`);
    process.exit(0);
}

// ---------------------------------------------------------------------------
// Program setup
// ---------------------------------------------------------------------------

// `--check-dts` reads the same entries out of the BUILT declarations. The
// snapshot stays the one authority for what the surface is; this only asks
// whether the `.d.ts` a consumer installs still carries it, which is the one
// thing a source-only guard cannot see. It is a smaller claim than the snapshot
// makes — names, kinds and "it compiles" — because that is what survives being
// re-printed by a declaration bundler. Comparing rendered types across two
// programs compares their printers, not the API.
const fromDts = mode === '--check-dts';
// Where a consumer's resolver lands: the `types` package.json names for the entry, not the source path mirrored
// into dist (`src/postprocess/fxBasic.ts` ships as `dist/fx-basic/index.d.ts`).
const exportsMap = JSON.parse(readFileSync(join(SDK, 'package.json'), 'utf8')).exports;
const typesOf = (name) => {
    const types = exportsMap[name === 'index' ? '.' : `./${name.replace(/^index\./, '')}`]?.types;
    if (!types) throw new Error(`api-surface: package.json exports no types for the "${name}" entry`);
    return types.replace(/^\.\//, '');
};
const entryPaths = fromDts
    ? Object.fromEntries(Object.keys(ENTRIES).map((name) => [name, typesOf(name)]))
    : ENTRIES;

const { program, checker } = createSdkProgram(entryPaths, { strictLibCheck: fromDts });

/**
 * Every symbol any entry exports, by identity rather than by name. Identity is
 * load-bearing: the asset class is called `Assets` and so is the resource const
 * that holds one, so a name check reads the class as exported when only the const
 * is. The union across entries, since a shape exported from `physics` is nameable.
 */
const exportedSymbols = new Set();
for (const entryPath of Object.values(entryPaths)) {
    const sourceFile = program.getSourceFile(join(SDK, entryPath));
    const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
    if (!moduleSymbol) continue;
    for (const s of checker.getExportsOfModule(moduleSymbol)) {
        exportedSymbols.add(s);
        if (s.flags & ts.SymbolFlags.Alias) exportedSymbols.add(checker.getAliasedSymbol(s));
    }
}

const FMT = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/** Absolute source paths leak into typeToString via import("...") — strip them so the
 *  snapshot is machine-independent (a Windows `F:/…` and a Linux `/home/…` for the same
 *  symbol must not read as drift). First collapse our own SDK path to `~`, then drop the
 *  `import("<any path>").` qualifier entirely — the trailing type name is what identifies
 *  the symbol, and the path is environment noise. */
function normalizeType(text) {
    return text
        .split(SDK.replace(/\\/g, '/')).join('~')
        .replace(/import\((['"]).*?\1\)\./g, '')
        .replace(/"[^"\\]*"(?: \| "[^"\\]*")+/g, (run) => run.split(' | ').sort().join(' | '));
}

const fileTagCache = new Map();

/**
 * Tier from a file's leading `@file` JSDoc header, as a module-wide fallback.
 * A header cannot confer @public: declaration bundlers drop it, so the freeze
 * would be invisible in the `.d.ts` a creator actually reads.
 */
function fileLevelTier(sourceFile) {
    if (fileTagCache.has(sourceFile.fileName)) return fileTagCache.get(sourceFile.fileName);
    let tier = null;
    const text = sourceFile.getFullText();
    for (const range of ts.getLeadingCommentRanges(text, 0) ?? []) {
        const comment = text.slice(range.pos, range.end);
        // Every comment before the first token is "leading", so the doc on a
        // file's first declaration is in here too. `@file` is what makes one a
        // header, and tagging that declaration is not tagging the module.
        if (!comment.startsWith('/**') || !/@file\b/.test(comment)) continue;
        if (/^\s*\*\s*@public\b/m.test(comment)) {
            const where = relative(ROOT, sourceFile.fileName).replace(/\\/g, '/');
            errors.push(`R4: '${where}' claims @public in its @file header — tag the declaration, a header does not reach the .d.ts`);
        }
        for (const t of ['internal', 'beta', 'experimental']) {
            if (new RegExp(`^\\s*\\*\\s*@${t}\\b`, 'm').test(comment)) { tier = t; break; }
        }
    }
    fileTagCache.set(sourceFile.fileName, tier);
    return tier;
}

/** Every JSDoc tag name on a symbol's declarations. */
function tagNames(symbol) {
    const out = new Set();
    for (const decl of symbol.declarations ?? []) {
        for (const tag of ts.getJSDocTags(decl)) out.add(tag.tagName.text);
    }
    return out;
}

/**
 * Tier and deprecation, as separate axes: a symbol can be frozen AND on its way
 * out, and the baseline rule needs to read the second without losing the first.
 * Declaration-site tag wins; else the declaring file's header; else experimental.
 */
function releaseTag(symbol) {
    const tags = tagNames(symbol);
    const deprecated = tags.has('deprecated');
    for (const t of TIERS) if (tags.has(t)) return { tier: t, deprecated };
    for (const decl of symbol.declarations ?? []) {
        const tier = fileLevelTier(decl.getSourceFile());
        if (tier) return { tier, deprecated };
    }
    return { tier: 'experimental', deprecated };
}

/** A member inherited from an ambient built-in (the TS lib or @types/node) — e.g. an
 *  `extends Error` class's `message`/`stack`, or `captureStackTrace` on ErrorConstructor.
 *  Its declaration lives in node_modules, so it floats with the installed @types version
 *  (this is what drifted CI: a newer @types/node augments ErrorConstructor). It is not the
 *  SDK's authored surface, so drop it. An SDK-authored override keeps at least one
 *  declaration outside node_modules and therefore survives. */
function isAmbientMember(member) {
    const decls = member.declarations;
    if (!decls || decls.length === 0) return false;
    return decls.every((d) => d.getSourceFile().fileName.replace(/\\/g, '/').includes('/node_modules/'));
}

/** A well-known symbol member — `__@iterator@16`, whose trailing id is a checker
 *  counter and therefore not stable enough to put in a snapshot. */
const WELL_KNOWN_SYMBOL = /^__@(\w+)@\d+$/;

/** `[Symbol.iterator]`, so `for…of` is part of the recorded surface. */
function memberName(member) {
    const wellKnown = WELL_KNOWN_SYMBOL.exec(member.escapedName?.toString() ?? '');
    return wellKnown ? `[Symbol.${wellKnown[1]}]` : member.name;
}

function isPrivateMember(member) {
    const escaped = member.escapedName?.toString() ?? '';
    if (WELL_KNOWN_SYMBOL.test(escaped)) return false;
    if (escaped.startsWith('__')) return true;
    for (const decl of member.declarations ?? []) {
        if (decl.name && ts.isPrivateIdentifier(decl.name)) return true;
        const mods = ts.canHaveModifiers(decl) ? ts.getModifiers(decl) : undefined;
        if (mods?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) {
            return true;
        }
    }
    return false;
}

const IS_MEMBER = (n) => ts.isPropertySignature(n) || ts.isMethodSignature(n) || ts.isPropertyDeclaration(n)
    || ts.isMethodDeclaration(n) || ts.isGetAccessor(n) || ts.isSetAccessor(n) || ts.isConstructorDeclaration(n);

/**
 * Whether the promised body carries this node. A private or `@internal` member is
 * in the `.d.ts` and promises nothing, so what its types name does not constrain
 * the promise; a constructor is the same — no snapshot line records it.
 */
function inUnpromisedMember(node) {
    for (let n = node; n; n = n.parent) {
        if (!IS_MEMBER(n)) continue;
        if (ts.isConstructorDeclaration(n)) return true;
        if (n.name && ts.isPrivateIdentifier(n.name)) return true;
        const mods = ts.canHaveModifiers(n) ? ts.getModifiers(n) : undefined;
        if (mods?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) return true;
        if (/@internal\b/.test(leadingDoc(n))) return true;
    }
    return false;
}

/**
 * R6 — types a frozen declaration names that no entry exports.
 *
 * check-tier-leaks compares tiers between snapshot entries, so a type absent from
 * the surface is invisible to it, and a @public signature can promise a shape whose
 * name a creator cannot write. Read from the AST: the checker prints an
 * out-of-scope type as a bare name, indistinguishable from an exported one.
 */
function unnameableTypes(decl) {
    const out = new Set();
    const walk = (node) => {
        if (ts.isTypeReferenceNode(node) && !inUnpromisedMember(node)) {
            const at = checker.getSymbolAtLocation(node.typeName);
            const target = at && (at.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(at) : at);
            if (target && !(target.flags & ts.SymbolFlags.TypeParameter) && !exportedSymbols.has(target)) {
                const from = target.declarations?.[0]?.getSourceFile().fileName.replace(/\\/g, '/');
                // Ours only: a lib or @types shape is not ours to export.
                if (from && from.startsWith(SDK.replace(/\\/g, '/')) && !from.includes('/node_modules/')) {
                    out.add(target.name);
                }
            }
        }
        ts.forEachChild(node, walk);
    };
    walk(decl);
    return [...out].sort();
}

function memberLines(type, location, owner) {
    const lines = [];
    for (const sig of type.getCallSignatures()) {
        lines.push(`call ${normalizeType(checker.signatureToString(sig, location, FMT))}`);
    }
    for (const sig of type.getConstructSignatures()) {
        lines.push(`new ${normalizeType(checker.signatureToString(sig, location, FMT))}`);
    }
    for (const member of type.getProperties()) {
        if (isPrivateMember(member)) continue;
        if (isAmbientMember(member)) continue;
        const memberType = checker.getTypeOfSymbolAtLocation(member, location);
        // R1 only ever saw top-level exports, so an @internal member rode out in the
        // public .d.ts unannounced. Marked here, in the shipped .d.ts, and skipped by
        // the leak and baseline rules: it is present, and it promises nothing.
        const mark = tagNames(member).has('internal') ? '@internal ' : '';
        lines.push(`${mark}${memberName(member)}: ${normalizeType(checker.typeToString(memberType, location, FMT))}`);
    }
    return lines.sort();
}

/**
 * The class or interface an alias points at when that target's OWN name is not
 * exported — `export type AssetsData = AssetsClass`, an alias for a class no entry
 * re-exports. Null for anything a reader can look up, or with no members to record.
 */
function hiddenTargetOf(aliasDecl) {
    if (!ts.isTypeReferenceNode(aliasDecl.type)) return null;
    const target = checker.getTypeAtLocation(aliasDecl.type).getSymbol();
    if (!target || !(target.flags & (ts.SymbolFlags.Class | ts.SymbolFlags.Interface))) return null;
    if (exportedSymbols.has(target)) return null;
    // Only our own source: an alias to a lib or @types shape is not ours to record.
    const from = target.declarations?.[0]?.getSourceFile().fileName.replace(/\\/g, '/');
    if (!from || !from.startsWith(SDK.replace(/\\/g, '/')) || from.includes('/node_modules/')) return null;
    return target;
}

function describeSymbol(name, symbol) {
    const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
    const decl = resolved.declarations?.[0];
    if (!decl) {
        errors.push(`R2: export '${name}' does not resolve to a declaration`);
        return null;
    }
    const { tier, deprecated } = releaseTag(resolved);
    if (tier === 'public') {
        for (const t of unnameableTypes(decl)) {
            errors.push(`R6: '${name}' is @public but names '${t}', which no entry exports — a creator cannot spell it`);
        }
    }
    const owner = { name, tier };
    const flags = resolved.flags;
    const body = [];
    let kind = 'value';

    if (flags & ts.SymbolFlags.Class) {
        kind = 'class';
        const instance = checker.getDeclaredTypeOfSymbol(resolved);
        const statics = checker.getTypeOfSymbolAtLocation(resolved, decl);
        body.push(...memberLines(instance, decl, owner));
        body.push(...memberLines(statics, decl, owner).map((l) => `static ${l}`));
    } else if (flags & ts.SymbolFlags.Interface) {
        kind = 'interface';
        body.push(...memberLines(checker.getDeclaredTypeOfSymbol(resolved), decl, owner));
    } else if (flags & ts.SymbolFlags.TypeAlias) {
        kind = 'type';
        const aliasDecl = resolved.declarations.find(ts.isTypeAliasDeclaration);
        const hidden = aliasDecl && hiddenTargetOf(aliasDecl);
        if (hidden) {
            // Recording the target's unexported NAME records nothing — no member
            // would reach the snapshot, the diff or the baseline rule. The type AT
            // the reference, so a `GraphEdge<FsmTransition>` keeps its instantiation.
            body.push(...memberLines(checker.getTypeAtLocation(aliasDecl.type), aliasDecl, owner));
            if (hidden.flags & ts.SymbolFlags.Class) {
                const statics = checker.getTypeOfSymbolAtLocation(hidden, hidden.declarations[0]);
                body.push(...memberLines(statics, aliasDecl, owner).map((l) => `static ${l}`));
            }
        } else {
            body.push(normalizeType(aliasDecl ? aliasDecl.type.getText() : 'unknown'));
        }
    } else if (flags & ts.SymbolFlags.Enum) {
        kind = 'enum';
        for (const m of resolved.exports?.values() ?? []) {
            const v = checker.getConstantValue?.(m.declarations?.[0]);
            body.push(`${m.name}${v !== undefined ? ` = ${JSON.stringify(v)}` : ''}`);
        }
        body.sort();
    } else if (flags & (ts.SymbolFlags.Function | ts.SymbolFlags.Variable | ts.SymbolFlags.BlockScopedVariable)) {
        kind = flags & ts.SymbolFlags.Function ? 'function' : 'const';
        const type = checker.getTypeOfSymbolAtLocation(resolved, decl);
        const calls = type.getCallSignatures();
        if (calls.length > 0 && kind === 'function') {
            for (const sig of calls) body.push(normalizeType(checker.signatureToString(sig, decl, FMT)));
            body.sort();
        } else {
            body.push(normalizeType(checker.typeToString(type, decl, FMT)));
        }
    } else if (flags & (ts.SymbolFlags.NamespaceModule | ts.SymbolFlags.ValueModule)) {
        kind = 'namespace';
        for (const m of checker.getExportsOfModule(resolved)) body.push(m.name);
        body.sort();
    }
    return { name, kind, tier, deprecated, body };
}

// ---------------------------------------------------------------------------
// Report generation + policy
// ---------------------------------------------------------------------------

function buildReport(entryName, entryPath) {
    const sourceFile = program.getSourceFile(join(SDK, entryPath));
    if (!sourceFile) throw new Error(`entry not found: ${entryPath}`);
    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
    if (!moduleSymbol) throw new Error(`no module symbol: ${entryPath}`);

    const exports = checker.getExportsOfModule(moduleSymbol)
        .filter((s) => !s.name.startsWith('__'))
        .sort((a, b) => (a.name < b.name ? -1 : 1));

    const out = [];
    out.push(`# API surface — esengine/${entryName}`);
    out.push('');
    out.push('<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->');
    out.push('');
    const counts = { public: 0, beta: 0, experimental: 0, deprecated: 0 };
    for (const symbol of exports) {
        const desc = describeSymbol(symbol.name, symbol);
        if (!desc) continue;
        if (desc.tier === 'internal') {
            errors.push(`R1: '${entryName}' exports @internal symbol '${symbol.name}'`);
            continue;
        }
        counts[desc.tier]++;
        if (desc.deprecated) counts.deprecated++;
        const suffix = ` @${desc.tier}${desc.deprecated ? ' @deprecated' : ''}`;
        out.push(`## ${desc.name} — ${desc.kind}${suffix}`);
        if (desc.body.length) {
            out.push('```');
            out.push(...desc.body);
            out.push('```');
        }
        out.push('');
    }
    out.splice(3, 0, `Symbols: ${counts.public} public · ${counts.beta} beta · ${counts.experimental} experimental · ${counts.deprecated} deprecated`);
    // Multi-line declaration bodies are extracted verbatim from source text, so
    // on a CRLF checkout they carry \r — normalize so the snapshot (and the
    // drift compare below) is byte-identical across platforms.
    return (out.join('\n') + '\n').replace(/\r\n?/g, '\n');
}

if (fromDts) {
    let broken = 0;
    // Only our own output: with skipLibCheck off, the installed @types are fair
    // game for the checker too, and their errors are not ours to fix.
    const DIST = join(SDK, 'dist');
    const diagnostics = program.getSemanticDiagnostics().concat(program.getSyntacticDiagnostics())
        .filter((d) => d.file?.fileName.startsWith(DIST.replace(/\\/g, '/')));
    if (diagnostics.length) {
        broken++;
        console.error(`INVALID: the built .d.ts does not compile — ${diagnostics.length} error(s)`);
        for (const d of diagnostics.slice(0, 10)) {
            const where = d.file ? `${d.file.fileName.replace(SDK + '/', '')}:${d.file.getLineAndCharacterOfPosition(d.start ?? 0).line + 1} ` : '';
            console.error(`  ${where}${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`);
        }
    }

    for (const [entryName, entryPath] of Object.entries(entryPaths)) {
        const sourceFile = program.getSourceFile(join(SDK, entryPath));
        const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
        if (!moduleSymbol) {
            broken++;
            console.error(`INVALID: ${entryName} — ${entryPath} is not a module`);
            continue;
        }
        const emitted = new Map();
        const declared = new Map();
        for (const symbol of checker.getExportsOfModule(moduleSymbol)) {
            if (symbol.name.startsWith('__')) continue;
            const desc = describeSymbol(symbol.name, symbol);
            if (!desc) continue;
            emitted.set(desc.name, desc.kind);
            const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
            if (resolved.declarations?.[0]) declared.set(desc.name, resolved.declarations[0]);
        }

        // Only name and kind are compared: a tier can come from a `@file` header,
        // and a header cannot survive into a bundled .d.ts.
        const snapshot = parseSnapshot(readFileSync(join(ETC, `${entryName}.api.md`), 'utf8'));

        // A freeze the creator's editor cannot show them is not a promise they
        // can act on, and a dropped tag is invisible without something asking.
        for (const [name, s] of snapshot) {
            if (s.tier !== 'public') continue;
            const decl = declared.get(name);
            if (decl && !/@public\b/.test(leadingDoc(decl))) {
                errors.push(`R5: '${name}' is @public but the built ${entryName}.d.ts does not carry the tag`);
            }
        }

        const dropped = [...snapshot.keys()].filter((n) => !emitted.has(n));
        const extra = [...emitted.keys()].filter((n) => !snapshot.has(n));
        const rekinded = [...snapshot].filter(([n, s]) => emitted.has(n) && emitted.get(n) !== s.kind);
        if (!dropped.length && !extra.length && !rekinded.length) continue;

        broken++;
        console.error(`DIVERGED: ${entryName} — the built .d.ts does not carry the documented surface.`);
        for (const n of dropped.slice(0, 15)) console.error(`  missing from .d.ts: ${n}`);
        for (const n of extra.slice(0, 15)) console.error(`  only in .d.ts:      ${n}`);
        for (const [n, s] of rekinded.slice(0, 15)) console.error(`  ${n}: ${s.kind} became ${emitted.get(n)}`);
    }

    // One violation per symbol, not per entry that re-exports it.
for (const e of new Set(errors)) console.error(`POLICY ${e}`);
    if (broken || errors.length) {
        console.error('\napi-surface: the declaration build is not shipping the documented surface.');
        process.exit(1);
    }
    console.log(`api-surface: ${Object.keys(ENTRIES).length} entries — built .d.ts carries the documented surface.`);
    process.exit(0);
}

let drift = 0;
mkdirSync(ETC, { recursive: true });
for (const [entryName, entryPath] of Object.entries(entryPaths)) {
    const report = buildReport(entryName, entryPath);
    const file = join(ETC, `${entryName}.api.md`);
    if (mode === '--update') {
        writeFileSync(file, report);
        console.log(`wrote ${file}`);
    } else {
        const existing = existsSync(file)
            ? readFileSync(file, 'utf8').replace(/\r\n?/g, '\n')
            : '';
        if (existing !== report) {
            drift++;
            console.error(`DRIFT: ${entryName} — public API changed but sdk/etc/${entryName}.api.md was not updated.`);
            // Show WHICH lines drifted (set difference — order-independent, so it
            // survives insertions) so the guard is self-explanatory in CI logs.
            const was = new Set(existing.split('\n'));
            const now = new Set(report.split('\n'));
            const removed = [...was].filter((l) => !now.has(l) && l.trim());
            const added = [...now].filter((l) => !was.has(l) && l.trim());
            for (const l of removed.slice(0, 25)) console.error(`  - ${l}`);
            for (const l of added.slice(0, 25)) console.error(`  + ${l}`);
            if (removed.length > 25 || added.length > 25) {
                console.error(`  … (${removed.length} removed, ${added.length} added lines total)`);
            }
        }
    }
}

// One violation per symbol, not per entry that re-exports it.
for (const e of new Set(errors)) console.error(`POLICY ${e}`);
if (errors.length || drift) {
    console.error(`\napi-surface: ${new Set(errors).size} policy violation(s), ${drift} drifted snapshot(s).`);
    console.error('Fix violations, then: node tools/api-surface.mjs --update');
    process.exit(1);
}
console.log(`api-surface: ${Object.keys(ENTRIES).length} entries clean.`);