@defold-typescript/types 0.19.3 → 0.20.0

package/scripts/generate-api-availability.ts

@@ -0,0 +1,139 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  type ApiAvailability,
+  type ApiMigrationCatalog,
+  applyMigrationOverlay,
+  collectSymbolIdentities,
+  deriveAvailabilityMatrix,
+  symbolIdentityKey,
+  type VersionSurface,
+  validateAvailability,
+} from "../src/api-availability";
+import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
+import { type ApiTarget, loadApiTargets, loadTargetModules } from "./regen";
+
+const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const MIGRATIONS_PATH = resolve(PACKAGE_ROOT, "api-migrations.json");
+const AVAILABILITY_PATH = resolve(PACKAGE_ROOT, "api-availability.json");
+
+const VERSION_FROM_ID = /^defold-(\d+\.\d+\.\d+)$/;
+
+export interface AvailabilityArtifact {
+  readonly versions: readonly string[];
+  readonly records: readonly ApiAvailability[];
+}
+
+export function versionOf(target: ApiTarget): string {
+  const match = VERSION_FROM_ID.exec(target.id);
+  if (!match?.[1]) throw new Error(`cannot derive a release version from target id "${target.id}"`);
+  return match[1];
+}
+
+function versionTuple(version: string): number[] {
+  return version.split(".").map((part) => Number.parseInt(part, 10));
+}
+
+function compareVersions(a: string, b: string): number {
+  const [ta, tb] = [versionTuple(a), versionTuple(b)];
+  for (let index = 0; index < Math.max(ta.length, tb.length); index += 1) {
+    const diff = (ta[index] ?? 0) - (tb[index] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+// Every complete committed surface, newest first. The committed targets are the
+// `source == null` entries of `api-targets.json` (ref-doc-sourced historical
+// targets are resolved on demand and never a committed-derivation input). This
+// registry-derived, version-desc list is the single source for the availability
+// version axis — it mirrors the CLI `DEFOLD_VERSIONS` order without inverting
+// the package layering (`types` must not import `cli`).
+export function selectCompleteVersionSurfaces(targets: readonly ApiTarget[]): ApiTarget[] {
+  const complete = targets
+    .filter((target) => (target.source ?? null) == null)
+    .sort((a, b) => compareVersions(versionOf(b), versionOf(a)));
+  if (complete.length === 0) {
+    throw new Error("api-targets.json has no committed (source == null) targets");
+  }
+  return complete;
+}
+
+export function loadMigrationCatalog(path: string = MIGRATIONS_PATH): ApiMigrationCatalog {
+  const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (
+    typeof raw !== "object" ||
+    raw === null ||
+    !Array.isArray((raw as { migrations?: unknown }).migrations)
+  ) {
+    throw new Error(`${path}: expected an object with a "migrations" array`);
+  }
+  return raw as ApiMigrationCatalog;
+}
+
+export interface BuildAvailabilityOptions {
+  readonly packageRoot?: string;
+  readonly registryPath?: string;
+  readonly catalog?: ApiMigrationCatalog;
+}
+
+export function buildAvailabilityArtifact(
+  options: BuildAvailabilityOptions = {},
+): AvailabilityArtifact {
+  const packageRoot = options.packageRoot ?? PACKAGE_ROOT;
+  const registryPath = options.registryPath ?? resolve(packageRoot, "api-targets.json");
+  const targets = loadApiTargets(registryPath);
+  const completeTargets = selectCompleteVersionSurfaces(targets);
+  const parse = (target: ApiTarget): ApiModule[] =>
+    loadTargetModules(target, packageRoot).map((entry) => parseDefoldApiDoc(entry.doc));
+  const surfaces: VersionSurface[] = completeTargets.map((target) => ({
+    version: versionOf(target),
+    modules: parse(target),
+  }));
+  const versions = surfaces.map((surface) => surface.version);
+
+  const derived = deriveAvailabilityMatrix({ surfaces });
+  const catalog =
+    options.catalog ?? loadMigrationCatalog(resolve(packageRoot, "api-migrations.json"));
+  const universe = collectSymbolIdentities(surfaces.flatMap((surface) => surface.modules));
+  const records = applyMigrationOverlay({ derived, catalog, universe, versions });
+
+  const newestSurface = surfaces[0] as VersionSurface;
+  const currentSurface = new Set(
+    collectSymbolIdentities(newestSurface.modules).map(symbolIdentityKey),
+  );
+  const knownIdentities = new Set(universe.map(symbolIdentityKey));
+  const errors = validateAvailability({ records, versions, currentSurface, knownIdentities });
+  if (errors.length > 0) {
+    throw new Error(`api-availability validation failed:\n  ${errors.join("\n  ")}`);
+  }
+
+  return { versions, records };
+}
+
+function biomeFormatJson(raw: string): string {
+  const out = Bun.spawnSync(
+    ["bunx", "biome", "format", "--stdin-file-path=api-availability.json"],
+    {
+      stdin: Buffer.from(raw),
+    },
+  );
+  if (out.exitCode !== 0) {
+    throw new Error(`biome format failed: ${out.stderr.toString()}`);
+  }
+  return out.stdout.toString();
+}
+
+export function serializeAvailabilityArtifact(artifact: AvailabilityArtifact): string {
+  return biomeFormatJson(JSON.stringify(artifact));
+}
+
+if (import.meta.main) {
+  const artifact = buildAvailabilityArtifact();
+  if (process.argv.includes("--write")) {
+    Bun.write(AVAILABILITY_PATH, serializeAvailabilityArtifact(artifact));
+    console.log(`wrote ${AVAILABILITY_PATH} (${artifact.records.length} records)`);
+  } else {
+    process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+  }
+}

package/scripts/generate-api-signatures.ts

@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import { symbolIdentityKey } from "../src/api-availability";
+import { selectCompleteVersionSurfaces, versionOf } from "./generate-api-availability";
+import { generateModuleSignatures, loadApiTargets, loadTargetModules } from "./regen";
+
+const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
+
+export interface SignaturesArtifact {
+  // version -> symbolIdentityKey -> authoritative TS signature text
+  readonly versions: Record<string, Record<string, string>>;
+}
+
+export interface BuildSignaturesOptions {
+  readonly packageRoot?: string;
+  readonly registryPath?: string;
+}
+
+function sortObjectKeys(record: Record<string, string>): Record<string, string> {
+  const sorted: Record<string, string> = {};
+  for (const key of Object.keys(record).sort()) sorted[key] = record[key] as string;
+  return sorted;
+}
+
+export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): SignaturesArtifact {
+  const packageRoot = options.packageRoot ?? PACKAGE_ROOT;
+  const registryPath = options.registryPath ?? resolve(packageRoot, "api-targets.json");
+  const targets = selectCompleteVersionSurfaces(loadApiTargets(registryPath));
+  const versions: Record<string, Record<string, string>> = {};
+  for (const target of targets) {
+    const version = versionOf(target);
+    const perSymbol: Record<string, string> = {};
+    for (const entry of loadTargetModules(target, packageRoot)) {
+      for (const { identity, tsSignature } of generateModuleSignatures(entry)) {
+        perSymbol[symbolIdentityKey(identity)] = tsSignature;
+      }
+    }
+    versions[version] = sortObjectKeys(perSymbol);
+  }
+  return { versions };
+}
+
+function biomeFormatJson(raw: string): string {
+  const out = Bun.spawnSync(["bunx", "biome", "format", "--stdin-file-path=api-signatures.json"], {
+    stdin: Buffer.from(raw),
+  });
+  if (out.exitCode !== 0) {
+    throw new Error(`biome format failed: ${out.stderr.toString()}`);
+  }
+  return out.stdout.toString();
+}
+
+export function serializeSignaturesArtifact(artifact: SignaturesArtifact): string {
+  return biomeFormatJson(JSON.stringify(artifact));
+}
+
+if (import.meta.main) {
+  const artifact = buildSignaturesArtifact();
+  if (process.argv.includes("--write")) {
+    Bun.write(SIGNATURES_PATH, serializeSignaturesArtifact(artifact));
+    const count = Object.values(artifact.versions).reduce((n, v) => n + Object.keys(v).length, 0);
+    console.log(`wrote ${SIGNATURES_PATH} (${count} signatures)`);
+  } else {
+    process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+  }
+}

package/scripts/import-defold-release.ts

@@ -0,0 +1,480 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { isKnownDefoldTypeToken } from "../src/emit-dts";
+import { refDocCacheDir, resolveRefDoc } from "./doc-source";
+import {
+  apiElementIdentity,
+  IGNORED_UPSTREAM,
+  mergeApiDocs,
+  readZip,
+  SYNC_MANIFEST,
+  type ZipAccessor,
+} from "./sync-api-docs";
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+const LUA_NAMESPACE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
+const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+
+export const DEFOLD_1_13_PROMOTED_NAMESPACES = [
+  "b2d.chain",
+  "b2d.fixture",
+  "b2d.joint",
+  "b2d.shape",
+  "b2d.world",
+  "compute",
+  "material",
+] as const;
+
+interface RawElement extends Record<string, unknown> {
+  type?: string;
+  name?: string;
+}
+
+interface RawApiDoc extends Record<string, unknown> {
+  info?: { namespace?: string };
+  elements?: RawElement[];
+}
+
+export interface ReleaseBaselineModule {
+  readonly namespace: string;
+  readonly fixture: string;
+  readonly doc: unknown;
+  readonly sourceEntries?: readonly string[];
+}
+
+export interface ReleaseBaseline {
+  readonly id: string;
+  readonly modules: readonly ReleaseBaselineModule[];
+  readonly luaStdlib: readonly ReleaseBaselineModule[];
+}
+
+export interface ReleaseImportSnapshot {
+  readonly namespace: string;
+  readonly fixture: string;
+  readonly doc: unknown;
+  readonly sourceEntries: readonly string[];
+  readonly symbolSources: readonly SymbolSource[];
+}
+
+interface SymbolSource {
+  readonly identity: string;
+  readonly name: string;
+  readonly kind: string;
+  readonly sourceEntries: string[];
+}
+
+interface ReleaseSource {
+  readonly namespace: string;
+  readonly entries: string[];
+  readonly functionCount: number;
+}
+
+interface NamespaceDelta {
+  readonly added: string[];
+  readonly removed: string[];
+}
+
+interface SymbolDelta {
+  readonly namespace: string;
+  readonly added: string[];
+  readonly removed: string[];
+}
+
+interface MovedNamespace {
+  readonly namespace: string;
+  readonly from: string[];
+  readonly to: string[];
+}
+
+interface UnknownTypeBlocker {
+  readonly namespace: string;
+  readonly symbol: string;
+  readonly tokens: string[];
+}
+
+interface UnmappedNamespaceBlocker {
+  readonly namespace: string;
+  readonly entries: string[];
+  readonly symbols: string[];
+}
+
+export interface ReleaseImportManifest {
+  readonly version: string;
+  readonly baseline: string;
+  readonly ready: boolean;
+  readonly sources: ReleaseSource[];
+  readonly namespaces: NamespaceDelta;
+  readonly moved: MovedNamespace[];
+  readonly symbols: SymbolDelta[];
+  readonly blockers: {
+    readonly unknownTypes: UnknownTypeBlocker[];
+    readonly unmappedFunctionNamespaces: UnmappedNamespaceBlocker[];
+  };
+  readonly snapshots: Array<{
+    readonly namespace: string;
+    readonly fixture: string;
+    readonly sourceEntries: readonly string[];
+    readonly symbols: readonly SymbolSource[];
+  }>;
+}
+
+export type ReleaseImportPlan = Omit<ReleaseImportManifest, "snapshots"> & {
+  readonly manifest: ReleaseImportManifest;
+  readonly snapshots: ReleaseImportSnapshot[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parsedDoc(raw: string): RawApiDoc | null {
+  try {
+    const value: unknown = JSON.parse(raw);
+    return isRecord(value) ? (value as RawApiDoc) : null;
+  } catch {
+    return null;
+  }
+}
+
+function namespaceOf(doc: RawApiDoc): string | null {
+  const namespace = isRecord(doc.info) ? doc.info.namespace : undefined;
+  return typeof namespace === "string" && LUA_NAMESPACE.test(namespace) ? namespace : null;
+}
+
+function elementsOf(doc: unknown): RawElement[] {
+  if (!isRecord(doc) || !Array.isArray(doc.elements)) return [];
+  return doc.elements.filter(isRecord) as RawElement[];
+}
+
+function symbolNames(doc: unknown): string[] {
+  return [
+    ...new Set(elementsOf(doc).flatMap((element) => (element.name ? [element.name] : []))),
+  ].sort();
+}
+
+function expectedSourceEntries(module: ReleaseBaselineModule): string[] {
+  if (module.sourceEntries) return [...module.sourceEntries].sort();
+  const mapped = SYNC_MANIFEST.find((entry) => entry.namespace === module.namespace);
+  if (mapped) return [mapped.zipEntry, ...(mapped.mergeEntries ?? [])].sort();
+  return [`doc/${module.namespace.replace(/\./g, "_")}.json`];
+}
+
+function typeTokens(value: unknown, out: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const item of value) typeTokens(item, out);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (Array.isArray(value.types)) {
+    for (const token of value.types) {
+      if (typeof token === "string" && !isKnownDefoldTypeToken(token)) out.add(token);
+    }
+  }
+  for (const nested of Object.values(value)) typeTokens(nested, out);
+}
+
+function unknownTypeBlockers(
+  namespace: string,
+  doc: unknown,
+  knownConstants: ReadonlySet<string>,
+): UnknownTypeBlocker[] {
+  const out: UnknownTypeBlocker[] = [];
+  for (const element of elementsOf(doc)) {
+    const tokens = new Set<string>();
+    typeTokens(element, tokens);
+    for (const token of knownConstants) tokens.delete(token);
+    if (tokens.size === 0) continue;
+    out.push({ namespace, symbol: element.name ?? "<unnamed>", tokens: [...tokens].sort() });
+  }
+  return out;
+}
+
+function reportWithoutSnapshots(plan: Omit<ReleaseImportPlan, "manifest">): ReleaseImportManifest {
+  return {
+    version: plan.version,
+    baseline: plan.baseline,
+    ready: plan.ready,
+    sources: plan.sources,
+    namespaces: plan.namespaces,
+    moved: plan.moved,
+    symbols: plan.symbols,
+    blockers: plan.blockers,
+    snapshots: plan.snapshots.map(({ namespace, fixture, sourceEntries, symbolSources }) => ({
+      namespace,
+      fixture,
+      sourceEntries,
+      symbols: symbolSources,
+    })),
+  };
+}
+
+export function buildReleaseImportPlan(input: {
+  version: string;
+  zip: ZipAccessor;
+  baseline: ReleaseBaseline;
+}): ReleaseImportPlan {
+  if (!EXACT_VERSION.test(input.version)) {
+    throw new Error(`expected an exact Defold release version, received '${input.version}'`);
+  }
+
+  const grouped = new Map<string, Array<{ entry: string; doc: RawApiDoc }>>();
+  for (const zipEntry of [...input.zip.entries()].sort()) {
+    const doc = parsedDoc(input.zip.read(zipEntry));
+    if (!doc) continue;
+    const namespace = namespaceOf(doc);
+    if (!namespace) continue;
+    const group = grouped.get(namespace) ?? [];
+    group.push({ entry: zipEntry, doc });
+    grouped.set(namespace, group);
+  }
+
+  const baselineModules = [...input.baseline.modules, ...input.baseline.luaStdlib];
+  const generatedNamespaces = new Set(input.baseline.modules.map((module) => module.namespace));
+  const baselineByNamespace = new Map(baselineModules.map((module) => [module.namespace, module]));
+  const incomingNamespaces = [...grouped.keys()].sort();
+  const baselineNamespaces = [...baselineByNamespace.keys()].sort();
+  const namespaces = {
+    added: incomingNamespaces.filter((namespace) => !baselineByNamespace.has(namespace)),
+    removed: baselineNamespaces.filter((namespace) => !grouped.has(namespace)),
+  };
+
+  const sources: ReleaseSource[] = incomingNamespaces.map((namespace) => {
+    const group = grouped.get(namespace) as Array<{ entry: string; doc: RawApiDoc }>;
+    return {
+      namespace,
+      entries: group.map(({ entry }) => entry).sort(),
+      functionCount: group.reduce(
+        (count, { doc }) =>
+          count + elementsOf(doc).filter((element) => element.type === "FUNCTION").length,
+        0,
+      ),
+    };
+  });
+
+  const knownConstants = new Set<string>();
+  for (const group of grouped.values()) {
+    for (const { doc } of group) {
+      for (const element of elementsOf(doc)) {
+        if (element.type === "CONSTANT" && typeof element.name === "string") {
+          knownConstants.add(element.name);
+        }
+      }
+    }
+  }
+
+  const snapshots: ReleaseImportSnapshot[] = [];
+  const moved: MovedNamespace[] = [];
+  const symbols: SymbolDelta[] = [];
+  const unknownTypes: UnknownTypeBlocker[] = [];
+  for (const module of baselineModules) {
+    const group = grouped.get(module.namespace);
+    if (!group) continue;
+    const sourceEntries = group.map(({ entry }) => entry).sort();
+    const doc = mergeApiDocs(group.map((item) => item.doc));
+    const symbolEntries = new Map<string, SymbolSource>();
+    for (const item of group) {
+      for (const element of elementsOf(item.doc)) {
+        const identity = apiElementIdentity(module.namespace, element);
+        if (!identity || typeof element.name !== "string" || typeof element.type !== "string")
+          continue;
+        const existing = symbolEntries.get(identity);
+        if (existing) existing.sourceEntries.push(item.entry);
+        else {
+          symbolEntries.set(identity, {
+            identity,
+            name: element.name,
+            kind: element.type,
+            sourceEntries: [item.entry],
+          });
+        }
+      }
+    }
+    const symbolSources = [...symbolEntries.values()]
+      .map((symbol) => ({ ...symbol, sourceEntries: [...new Set(symbol.sourceEntries)].sort() }))
+      .sort((a, b) => a.identity.localeCompare(b.identity));
+    snapshots.push({
+      namespace: module.namespace,
+      fixture: module.fixture,
+      doc,
+      sourceEntries,
+      symbolSources,
+    });
+
+    const expected = expectedSourceEntries(module);
+    if (expected.some((entry) => !sourceEntries.includes(entry))) {
+      moved.push({ namespace: module.namespace, from: expected, to: sourceEntries });
+    }
+
+    const before = new Set(symbolNames(module.doc));
+    const after = new Set(symbolNames(doc));
+    const added = [...after].filter((name) => !before.has(name)).sort();
+    const removed = [...before].filter((name) => !after.has(name)).sort();
+    if (added.length > 0 || removed.length > 0)
+      symbols.push({ namespace: module.namespace, added, removed });
+    if (generatedNamespaces.has(module.namespace)) {
+      unknownTypes.push(...unknownTypeBlockers(module.namespace, doc, knownConstants));
+    }
+  }
+
+  const unmappedFunctionNamespaces = sources
+    .filter(
+      (source) =>
+        source.functionCount > 0 &&
+        !baselineByNamespace.has(source.namespace) &&
+        !IGNORED_UPSTREAM.has(source.namespace),
+    )
+    .map((source) => ({
+      namespace: source.namespace,
+      entries: source.entries,
+      symbols: symbolNames(
+        mergeApiDocs((grouped.get(source.namespace) ?? []).map((item) => item.doc)),
+      ).filter((name) =>
+        elementsOf(
+          mergeApiDocs((grouped.get(source.namespace) ?? []).map((item) => item.doc)),
+        ).some((element) => element.type === "FUNCTION" && element.name === name),
+      ),
+    }));
+
+  snapshots.sort((a, b) => a.namespace.localeCompare(b.namespace));
+  moved.sort((a, b) => a.namespace.localeCompare(b.namespace));
+  symbols.sort((a, b) => a.namespace.localeCompare(b.namespace));
+  unknownTypes.sort(
+    (a, b) => a.namespace.localeCompare(b.namespace) || a.symbol.localeCompare(b.symbol),
+  );
+  const ready = unknownTypes.length === 0 && unmappedFunctionNamespaces.length === 0;
+  const planBase = {
+    version: input.version,
+    baseline: input.baseline.id,
+    ready,
+    sources,
+    namespaces,
+    moved,
+    symbols,
+    blockers: { unknownTypes, unmappedFunctionNamespaces },
+    snapshots,
+  };
+  const manifest = reportWithoutSnapshots(planBase);
+  return { ...planBase, manifest };
+}
+
+export function releaseImportReportJson(plan: ReleaseImportPlan): string {
+  return `${JSON.stringify(plan.manifest, null, 2)}\n`;
+}
+
+export function applyReleaseImport(plan: ReleaseImportPlan, packageRoot = PACKAGE_ROOT): string[] {
+  if (!plan.ready)
+    throw new Error("release import is blocked; resolve every reported blocker first");
+  const relativeRoot = `fixtures/defold-${plan.version}`;
+  const written: string[] = [];
+  for (const snapshot of plan.snapshots) {
+    const relative = `${relativeRoot}/${snapshot.fixture}`;
+    const path = resolve(packageRoot, relative);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(snapshot.doc, null, 2)}\n`);
+    written.push(relative);
+  }
+  const manifestPath = `${relativeRoot}/import-manifest.json`;
+  writeFileSync(resolve(packageRoot, manifestPath), releaseImportReportJson(plan));
+  written.push(manifestPath);
+  return written.sort();
+}
+
+export interface ReleaseImportArgs {
+  readonly version: string;
+  readonly check: boolean;
+  readonly json: boolean;
+  readonly zipPath?: string;
+}
+
+export function parseReleaseImportArgs(args: readonly string[]): ReleaseImportArgs {
+  const version = args[0];
+  if (!version || !EXACT_VERSION.test(version)) {
+    throw new Error(
+      "import-defold-release requires an exact Defold release version (for example 1.13.0)",
+    );
+  }
+  let check = false;
+  let json = false;
+  let zipPath: string | undefined;
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--check") check = true;
+    else if (arg === "--json") json = true;
+    else if (arg === "--zip") {
+      zipPath = args[index + 1];
+      if (!zipPath || zipPath.startsWith("--")) throw new Error("--zip requires a path");
+      index += 1;
+    } else {
+      throw new Error(`unknown argument '${arg}'`);
+    }
+  }
+  return { version, check, json, ...(zipPath ? { zipPath } : {}) };
+}
+
+function loadBaseline(packageRoot = PACKAGE_ROOT): ReleaseBaseline {
+  const registry = JSON.parse(readFileSync(resolve(packageRoot, "api-targets.json"), "utf8")) as {
+    targets: Array<{
+      id: string;
+      default?: boolean;
+      fixturesDir: string;
+      modules: Array<{ namespace: string; fixture: string }>;
+      luaStdlib?: Array<{ namespace: string; fixture: string }>;
+    }>;
+  };
+  const target = registry.targets.find((candidate) => candidate.default === true);
+  if (!target) throw new Error("api-targets.json has no default baseline target");
+  const load = (module: { namespace: string; fixture: string }): ReleaseBaselineModule => ({
+    ...module,
+    doc: JSON.parse(readFileSync(resolve(packageRoot, target.fixturesDir, module.fixture), "utf8")),
+  });
+  const modules = target.modules
+    .filter((module) => SYNC_MANIFEST.some((source) => source.namespace === module.namespace))
+    .map(load);
+  for (const namespace of DEFOLD_1_13_PROMOTED_NAMESPACES) {
+    if (modules.some((module) => module.namespace === namespace)) continue;
+    modules.push({
+      namespace,
+      fixture: `${namespace.replace(/\./g, "_")}_doc.json`,
+      doc: { info: { namespace }, elements: [] },
+    });
+  }
+  return {
+    id: target.id,
+    modules,
+    luaStdlib: (target.luaStdlib ?? []).map(load),
+  };
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseReleaseImportArgs(process.argv.slice(2));
+    const resolved = args.zipPath
+      ? { zip: readZip(args.zipPath), provenance: "local" as const }
+      : await resolveRefDoc({ version: args.version, cacheDir: refDocCacheDir() });
+    const plan = buildReleaseImportPlan({
+      version: args.version,
+      zip: resolved.zip,
+      baseline: loadBaseline(),
+    });
+    if (args.json) process.stdout.write(releaseImportReportJson(plan));
+    else {
+      console.log(`Defold ${args.version} release import: ${plan.ready ? "ready" : "blocked"}`);
+      console.log(`  source: ${resolved.provenance}`);
+      console.log(
+        `  namespaces: +${plan.namespaces.added.length} -${plan.namespaces.removed.length}`,
+      );
+      console.log(`  moved: ${plan.moved.length}; symbol deltas: ${plan.symbols.length}`);
+      console.log(
+        `  blockers: ${plan.blockers.unknownTypes.length} unknown type symbol(s), ${plan.blockers.unmappedFunctionNamespaces.length} unmapped namespace(s)`,
+      );
+    }
+    if (!args.check && plan.ready) {
+      const written = applyReleaseImport(plan);
+      if (!args.json) console.log(`  wrote: ${written.join(", ")}`);
+    }
+    if (!plan.ready) process.exitCode = 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}