@defold-typescript/types 0.1.0

package/scripts/regen.ts

@@ -0,0 +1,294 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
+import { parseDefoldApiDoc } from "../src/api-doc";
+import { emitDeclarations } from "../src/emit-dts";
+import { emitBuiltinMessages, parseMessagesDoc } from "../src/emit-messages";
+import { wrapAsAmbientGlobal } from "../src/publish-dts";
+import { type DownloadRefDoc, refDocCacheDir, resolveRefDoc } from "./doc-source";
+import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
+
+export interface ApiTargetModule {
+  readonly namespace: string;
+  readonly fixture: string;
+  readonly outFile: string;
+  readonly skipFunctions?: readonly string[];
+}
+
+// A target sourced from a resolved ref-doc zip (resolved on demand, never
+// pre-baked) versus the committed-fixture default (`null`).
+export type ApiTargetSource = { readonly kind: "ref-doc"; readonly version: string } | null;
+
+export interface ApiTarget {
+  readonly id: string;
+  readonly default?: boolean;
+  readonly fixturesDir: string;
+  readonly generatedDir: string;
+  readonly coreTypesImport: string;
+  readonly source?: ApiTargetSource;
+  readonly modules: readonly ApiTargetModule[];
+}
+
+const REGISTRY_PATH = resolve(import.meta.dir, "..", "api-targets.json");
+const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+
+export function loadApiTargets(registryPath: string = REGISTRY_PATH): ApiTarget[] {
+  const { targets } = JSON.parse(readFileSync(registryPath, "utf8")) as { targets: ApiTarget[] };
+  const defaults = targets.filter((t) => t.default === true);
+  if (defaults.length !== 1) {
+    throw new Error(
+      `api-targets.json: expected exactly one default target, found ${defaults.length}`,
+    );
+  }
+  return targets;
+}
+
+export function loadTargetModules(
+  target: ApiTarget,
+  packageRoot: string = PACKAGE_ROOT,
+): ModuleManifestEntry[] {
+  return target.modules.map((module) => {
+    const path = resolve(packageRoot, target.fixturesDir, module.fixture);
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch {
+      throw new Error(
+        `api-targets.json: target "${target.id}" module "${module.namespace}" fixture not found: ${path}`,
+      );
+    }
+    const entry: ModuleManifestEntry = {
+      namespace: module.namespace,
+      doc: JSON.parse(raw),
+      outFile: module.outFile,
+      importsFrom: target.coreTypesImport,
+    };
+    return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
+  });
+}
+
+export interface ModuleManifestEntry {
+  readonly namespace: string;
+  readonly doc: unknown;
+  readonly outFile: string;
+  readonly skipFunctions?: readonly string[];
+  readonly importsFrom?: string;
+}
+
+export interface ResolveTargetOptions {
+  readonly cacheDir?: string;
+  readonly download?: DownloadRefDoc;
+  readonly readZip?: typeof readZip;
+  readonly syncManifest?: readonly SyncManifestEntry[];
+  readonly packageRoot?: string;
+}
+
+// Source-aware module resolution: a `null`-source target reads committed
+// fixtures from disk (delegates to loadTargetModules); a `ref-doc` target
+// resolves its docs on demand from the version's ref-doc zip, keyed by the
+// SYNC_MANIFEST namespace -> zip-entry map.
+export async function resolveTargetModules(
+  target: ApiTarget,
+  opts: ResolveTargetOptions = {},
+): Promise<ModuleManifestEntry[]> {
+  const source = target.source ?? null;
+  if (source == null) {
+    return loadTargetModules(target, opts.packageRoot);
+  }
+  const { zip } = await resolveRefDoc({
+    version: source.version,
+    cacheDir: opts.cacheDir ?? refDocCacheDir(),
+    ...(opts.download ? { download: opts.download } : {}),
+    ...(opts.readZip ? { readZip: opts.readZip } : {}),
+  });
+  const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
+  return target.modules.map((module) => {
+    const sync = syncManifest.find((s) => s.namespace === module.namespace);
+    if (!sync) {
+      throw new Error(
+        `api-targets.json: target "${target.id}" module "${module.namespace}": no SYNC_MANIFEST zip entry`,
+      );
+    }
+    const entry: ModuleManifestEntry = {
+      namespace: module.namespace,
+      doc: JSON.parse(zip.read(sync.zipEntry)),
+      outFile: module.outFile,
+      importsFrom: target.coreTypesImport,
+    };
+    return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
+  });
+}
+
+const API_TARGETS = loadApiTargets();
+const DEFAULT_TARGET = API_TARGETS.find((t) => t.default === true) as ApiTarget;
+
+export const MODULE_MANIFEST: readonly ModuleManifestEntry[] = loadTargetModules(DEFAULT_TARGET);
+
+export interface MessagesManifestEntry {
+  readonly doc: unknown;
+  readonly outFile: string;
+}
+
+export const MESSAGES_MANIFEST: MessagesManifestEntry = {
+  doc: messagesDoc,
+  outFile: "builtin-messages.d.ts",
+};
+
+export function generateBuiltinMessagesDeclaration(entry: MessagesManifestEntry): string {
+  return emitBuiltinMessages(parseMessagesDoc(entry.doc));
+}
+
+export interface GenerateResult {
+  contents: string;
+  dropped: string[];
+}
+
+// Every CONSTANT FQN across the manifest, so a module's emit can brand a
+// constant token owned by a *different* module (e.g. render's
+// `graphics.BUFFER_TYPE_*` params) to the same FQN-keyed brand the owning
+// module's `const` declaration carries.
+export function collectConstantFqns(
+  manifest: readonly ModuleManifestEntry[] = MODULE_MANIFEST,
+): Set<string> {
+  const fqns = new Set<string>();
+  for (const entry of manifest) {
+    for (const c of parseDefoldApiDoc(entry.doc).constants) fqns.add(c.name);
+  }
+  return fqns;
+}
+
+export interface GenerateOptions {
+  knownConstantFqns?: ReadonlySet<string>;
+}
+
+export function generateModuleDeclaration(
+  entry: ModuleManifestEntry,
+  options?: GenerateOptions,
+): GenerateResult {
+  const module = parseDefoldApiDoc(entry.doc);
+  const prefix = `${module.namespace}.`;
+  const dropped: string[] = [];
+  const skip = new Set(entry.skipFunctions ?? []);
+  module.functions = module.functions.filter((fn) => {
+    const local = fn.name.startsWith(prefix) ? fn.name.slice(prefix.length) : fn.name;
+    if (skip.has(local)) {
+      dropped.push(fn.name);
+      return false;
+    }
+    return true;
+  });
+  const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
+  const emitted = emitDeclarations(module, { knownConstantFqns });
+  const contents = wrapAsAmbientGlobal({
+    namespace: module.namespace,
+    emitted,
+    importsFrom: entry.importsFrom ?? "../src/core-types",
+  });
+  return { contents, dropped };
+}
+
+export interface VersionedModuleManifestEntry extends ModuleManifestEntry {
+  readonly versionId: string;
+}
+
+// Committed generation covers only filesystem-fixture targets (source == null).
+// ref-doc targets are resolved on the fly and never pre-baked, so they are
+// excluded from the committed regen loop and the byte-drift guards.
+export const VERSIONED_MODULE_MANIFEST: readonly VersionedModuleManifestEntry[] =
+  API_TARGETS.filter(
+    (target) => target.default !== true && (target.source ?? null) == null,
+  ).flatMap((target) =>
+    loadTargetModules(target).map((entry) => ({ ...entry, versionId: target.id })),
+  );
+
+export const RESTRICTED_NAMESPACES: Readonly<Record<string, string>> = {
+  gui: "gui_script",
+  render: "render_script",
+};
+
+const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
+  "../builtin-messages",
+  "../../src/msg-overloads",
+  "../../src/go-overloads",
+];
+
+export interface KindManifestEntry {
+  readonly kind: string;
+  readonly restricted?: string;
+}
+
+export const KIND_MODULE_MANIFEST: readonly KindManifestEntry[] = [
+  { kind: "script" },
+  { kind: "gui-script", restricted: "gui" },
+  { kind: "render-script", restricted: "render" },
+];
+
+export function generateKindIndex(kind: string): string {
+  const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === kind);
+  if (!entry) throw new Error(`unknown script kind: ${kind}`);
+  const universalNamespaces = MODULE_MANIFEST.filter(
+    (m) => !Object.hasOwn(RESTRICTED_NAMESPACES, m.namespace),
+  ).map((m) => `../${m.outFile.replace(/\.d\.ts$/, "")}`);
+  const lines = [...UNIVERSAL_EXTRA_IMPORTS, ...universalNamespaces]
+    .sort()
+    .map((path) => `import "${path}";`);
+  if (entry.restricted) lines.push(`import "../${entry.restricted}";`);
+  return `${lines.join("\n")}\n\nexport {};\n`;
+}
+
+export function generateVersionIndex(
+  versionId: string,
+  manifest: readonly VersionedModuleManifestEntry[] = VERSIONED_MODULE_MANIFEST,
+): string {
+  const imports = manifest
+    .filter((entry) => entry.versionId === versionId)
+    .map((entry) => entry.outFile.replace(/\.d\.ts$/, ""))
+    .sort()
+    .map((module) => `import "./${module}";`)
+    .join("\n");
+  return `${imports}\n\nexport {};\n`;
+}
+
+if (import.meta.main) {
+  const generated = resolve(import.meta.dir, "..", "generated");
+  for (const entry of MODULE_MANIFEST) {
+    const { contents, dropped } = generateModuleDeclaration(entry);
+    if (dropped.length > 0) {
+      console.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
+    }
+    const out = resolve(generated, entry.outFile);
+    writeFileSync(out, contents);
+    console.log(`wrote ${out}`);
+  }
+  const messagesOut = resolve(generated, MESSAGES_MANIFEST.outFile);
+  writeFileSync(messagesOut, generateBuiltinMessagesDeclaration(MESSAGES_MANIFEST));
+  console.log(`wrote ${messagesOut}`);
+
+  const versionIds = new Set(VERSIONED_MODULE_MANIFEST.map((entry) => entry.versionId));
+  for (const entry of VERSIONED_MODULE_MANIFEST) {
+    const { contents, dropped } = generateModuleDeclaration(entry);
+    if (dropped.length > 0) {
+      console.log(
+        `note: dropped skipped member(s) from ${entry.versionId}/${entry.namespace}: ${dropped.join(", ")}`,
+      );
+    }
+    const versionDir = resolve(generated, "versions", entry.versionId);
+    mkdirSync(versionDir, { recursive: true });
+    const out = resolve(versionDir, entry.outFile);
+    writeFileSync(out, contents);
+    console.log(`wrote ${out}`);
+  }
+  for (const versionId of versionIds) {
+    const indexOut = resolve(generated, "versions", versionId, "index.d.ts");
+    writeFileSync(indexOut, generateVersionIndex(versionId));
+    console.log(`wrote ${indexOut}`);
+  }
+
+  const kindsDir = resolve(generated, "kinds");
+  mkdirSync(kindsDir, { recursive: true });
+  for (const entry of KIND_MODULE_MANIFEST) {
+    const out = resolve(kindsDir, `${entry.kind}.d.ts`);
+    writeFileSync(out, generateKindIndex(entry.kind));
+    console.log(`wrote ${out}`);
+  }
+}

package/scripts/sync-api-docs.ts

@@ -0,0 +1,375 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
+import { DEFOLD_TYPE_MAP } from "../src/core-types";
+import { parseScriptApi } from "../src/script-api";
+import { MODULE_MANIFEST } from "./regen";
+
+export const DEFOLD_VERSION = "1.12.4";
+export const refDocUrl = (version = DEFOLD_VERSION): string =>
+  `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
+
+export interface SyncManifestEntry {
+  readonly namespace: string;
+  readonly zipEntry: string;
+  readonly fixture: string;
+}
+
+// namespace -> ref-doc.zip entry. Entry paths do not match the namespace (gui ->
+// gui_script, go -> gameobject_script, most -> scripts-script_<n> / src-script_<n>),
+// so each path is confirmed against the pinned release artifact, not derived.
+export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
+  entry("b2d", "doc/scripts-box2d-script_box2d.cpp_doc.json"),
+  entry("buffer", "doc/scripts-script_buffer.cpp_doc.json"),
+  entry("camera", "doc/scripts-script_camera.cpp_doc.json"),
+  entry("collectionfactory", "doc/scripts-script_collection_factory.cpp_doc.json"),
+  entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json"),
+  entry("crash", "doc/script_crash.cpp_doc.json"),
+  entry("factory", "doc/scripts-script_factory.cpp_doc.json"),
+  entry("go", "doc/gameobject_script.cpp_doc.json"),
+  entry("graphics", "doc/src-script_graphics.cpp_doc.json"),
+  entry("gui", "doc/gui_script.cpp_doc.json"),
+  entry("http", "doc/scripts-script_http.cpp_doc.json"),
+  entry("image", "doc/scripts-script_image.cpp_doc.json"),
+  entry("json", "doc/src-script_json.cpp_doc.json"),
+  entry("label", "doc/scripts-script_label.cpp_doc.json"),
+  entry("liveupdate", "doc/src-script_liveupdate.h_doc.json"),
+  entry("model", "doc/scripts-script_model.cpp_doc.json"),
+  entry("msg", "doc/src-script_msg.cpp_doc.json"),
+  entry("particlefx", "doc/scripts-script_particlefx.cpp_doc.json"),
+  entry("physics", "doc/scripts-script_physics.cpp_doc.json"),
+  entry("profiler", "doc/profiler.cpp_doc.json"),
+  entry("render", "doc/render-render_script.cpp_doc.json"),
+  entry("resource", "doc/scripts-script_resource.cpp_doc.json"),
+  entry("socket", "doc/luasocket-luasocket.doc_h_doc.json"),
+  entry("sound", "doc/scripts-script_sound.cpp_doc.json"),
+  entry("sprite", "doc/scripts-script_sprite.cpp_doc.json"),
+  // The `sys` surface is split across two docs in ref-doc.zip; this is the core
+  // (src-script_sys) doc — the larger gamesys subset is folded in when wired.
+  entry("sys", "doc/src-script_sys.cpp_doc.json"),
+  entry("tilemap", "doc/scripts-script_tilemap.cpp_doc.json"),
+  entry("timer", "doc/src-script_timer.cpp_doc.json"),
+  entry("vmath", "doc/src-script_vmath.cpp_doc.json"),
+  entry("window", "doc/scripts-script_window.cpp_doc.json"),
+  entry("zlib", "doc/src-script_zlib.cpp_doc.json"),
+];
+
+// Checklist namespaces with no machine-readable doc anywhere (neither core
+// ref-doc.zip nor a published extension `.script_api`). Currently empty: the
+// four extension-only surfaces are wired via EXTENSION_MANIFEST below.
+export const UNMAPPED: ReadonlyMap<string, string> = new Map();
+
+function entry(namespace: string, zipEntry: string): SyncManifestEntry {
+  return { namespace, zipEntry, fixture: `fixtures/${namespace}_doc.json` };
+}
+
+export interface ExtensionManifestEntry {
+  readonly namespace: string;
+  readonly repo: string;
+  readonly tag: string;
+  readonly path: string;
+  readonly fixture: string;
+}
+
+// Extension-only namespaces: each ships a single `.script_api` (YAML) doc in
+// its own repo rather than appearing in core ref-doc.zip. Pinned to a release
+// tag and converted to the core ref-doc JSON shape via parseScriptApi so they
+// flow through MODULE_MANIFEST and the drift guard like every core namespace.
+export const EXTENSION_MANIFEST: readonly ExtensionManifestEntry[] = [
+  ext("iac", "defold/extension-iac", "1.4.0", "extension-iac/api/iac.script_api"),
+  ext("iap", "defold/extension-iap", "8.4.0", "extension-iap/api/iap.script_api"),
+  ext("push", "defold/extension-push", "4.1.0", "extension-push/api/push.script_api"),
+  ext("webview", "defold/extension-webview", "1.5.0", "webview/api/webview.script_api"),
+];
+
+function ext(namespace: string, repo: string, tag: string, path: string): ExtensionManifestEntry {
+  return { namespace, repo, tag, path, fixture: `fixtures/${namespace}_doc.json` };
+}
+
+export const extensionRawUrl = (e: ExtensionManifestEntry): string =>
+  `https://raw.githubusercontent.com/${e.repo}/${e.tag}/${e.path}`;
+
+// Convert a raw `.script_api` YAML doc to the core ref-doc JSON string written
+// to fixtures/<ns>_doc.json. The result is byte-compared by the same drift
+// semantics core fixtures use.
+export function scriptApiToFixtureJson(text: string): string {
+  return JSON.stringify(parseScriptApi(text));
+}
+
+// The types-api-coverage `What` checklist in vision.md lists every namespace as
+// a backtick-quoted token on the "Concrete breadth checklist" line. Reading it
+// here keeps SYNC_MANIFEST + UNMAPPED honest against the source of truth: the
+// coverage test fails if the checklist gains a namespace neither maps.
+export function parseChecklistNamespaces(visionMarkdown: string): string[] {
+  const start = visionMarkdown.indexOf("Concrete breadth checklist");
+  if (start === -1) return [];
+  const lineEnd = visionMarkdown.indexOf("\n", start);
+  const line = visionMarkdown.slice(start, lineEnd === -1 ? undefined : lineEnd);
+  const afterParen = line.slice(line.indexOf("):") + 2);
+  const shipped = afterParen.indexOf("Currently shipped");
+  const segment = shipped === -1 ? afterParen : afterParen.slice(0, shipped);
+  const namespaces: string[] = [];
+  const seen = new Set<string>();
+  for (const match of segment.matchAll(/`([^`]+)`/g)) {
+    const token = match[1] as string;
+    if (!/^[a-z][a-z0-9]*$/.test(token) || seen.has(token)) continue;
+    seen.add(token);
+    namespaces.push(token);
+  }
+  return namespaces;
+}
+
+export interface ZipAccessor {
+  has(entry: string): boolean;
+  read(entry: string): string;
+}
+
+export function readZip(path: string): ZipAccessor {
+  const list = Bun.spawnSync(["unzip", "-Z1", path]);
+  if (list.exitCode !== 0) {
+    throw new Error(`unzip -Z1 failed for ${path}: ${list.stderr.toString()}`);
+  }
+  const entries = new Set(list.stdout.toString().split("\n").filter(Boolean));
+  return {
+    has: (name) => entries.has(name),
+    read: (name) => {
+      const out = Bun.spawnSync(["unzip", "-p", path, name]);
+      if (out.exitCode !== 0) {
+        throw new Error(`unzip -p failed for ${name} in ${path}: ${out.stderr.toString()}`);
+      }
+      return out.stdout.toString();
+    },
+  };
+}
+
+export async function downloadZip(version = DEFOLD_VERSION): Promise<ZipAccessor> {
+  const url = refDocUrl(version);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`download failed: ${url} -> ${res.status} ${res.statusText}`);
+  }
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  const dir = mkdtempSync(join(tmpdir(), "defold-ref-doc-"));
+  const zipPath = join(dir, "ref-doc.zip");
+  writeFileSync(zipPath, bytes);
+  return readZip(zipPath);
+}
+
+export interface ExtractedFixture {
+  namespace: string;
+  fixture: string;
+  contents: string;
+}
+
+export function extractFixtures(
+  zip: ZipAccessor,
+  manifest: readonly SyncManifestEntry[] = SYNC_MANIFEST,
+): ExtractedFixture[] {
+  return manifest.map((item) => {
+    if (!zip.has(item.zipEntry)) {
+      throw new Error(`zip is missing entry ${item.zipEntry} for namespace ${item.namespace}`);
+    }
+    return { namespace: item.namespace, fixture: item.fixture, contents: zip.read(item.zipEntry) };
+  });
+}
+
+export type FixtureSyncStatus = "clean" | "drift" | "created";
+
+export interface FixtureSyncResult {
+  namespace: string;
+  fixture: string;
+  status: FixtureSyncStatus;
+}
+
+export interface SyncOptions {
+  fixturesRoot?: string;
+  check?: boolean;
+  manifest?: readonly SyncManifestEntry[];
+  format?: (raw: string) => string;
+}
+
+const PACKAGE_ROOT = resolve(import.meta.dir, "..");
+
+function canonicalJson(raw: string): string {
+  return JSON.stringify(JSON.parse(raw));
+}
+
+function biomeFormatJson(raw: string): string {
+  const out = Bun.spawnSync(["bunx", "biome", "format", "--stdin-file-path=fixture.json"], {
+    stdin: Buffer.from(raw),
+  });
+  if (out.exitCode !== 0) {
+    throw new Error(`biome format failed: ${out.stderr.toString()}`);
+  }
+  return out.stdout.toString();
+}
+
+export function syncFixtures(zip: ZipAccessor, options: SyncOptions = {}): FixtureSyncResult[] {
+  const manifest = options.manifest ?? SYNC_MANIFEST;
+  return syncExtractedFixtures(extractFixtures(zip, manifest), options);
+}
+
+// Compare/write a set of already-extracted fixtures against disk. Shared by
+// the core (zip) and extension (`.script_api`) sync paths so both honor the
+// identical created/clean/drift + format-on-write semantics.
+export function syncExtractedFixtures(
+  items: readonly ExtractedFixture[],
+  options: Omit<SyncOptions, "manifest"> = {},
+): FixtureSyncResult[] {
+  const root = options.fixturesRoot ?? PACKAGE_ROOT;
+  const check = options.check ?? false;
+  const format = options.format ?? biomeFormatJson;
+  const results: FixtureSyncResult[] = [];
+  for (const item of items) {
+    const path = resolve(root, item.fixture);
+    const existing = readFixtureOrNull(path);
+    const status: FixtureSyncStatus =
+      existing === null
+        ? "created"
+        : canonicalJson(existing) === canonicalJson(item.contents)
+          ? "clean"
+          : "drift";
+    if (!check && status !== "clean") {
+      writeFileSync(path, format(item.contents));
+    }
+    results.push({ namespace: item.namespace, fixture: item.fixture, status });
+  }
+  return results;
+}
+
+export async function downloadExtensionFixtures(
+  manifest: readonly ExtensionManifestEntry[] = EXTENSION_MANIFEST,
+): Promise<ExtractedFixture[]> {
+  const out: ExtractedFixture[] = [];
+  for (const e of manifest) {
+    const url = extensionRawUrl(e);
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(`extension doc download failed: ${url} -> ${res.status} ${res.statusText}`);
+    }
+    out.push({
+      namespace: e.namespace,
+      fixture: e.fixture,
+      contents: scriptApiToFixtureJson(await res.text()),
+    });
+  }
+  return out;
+}
+
+function readFixtureOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export interface SyncedDoc {
+  namespace: string;
+  doc: unknown;
+}
+
+export interface CoverageReport {
+  wired: string[];
+  fixtureOnly: string[];
+  missingMapping: string[];
+  unknownTypeTokens: { namespace: string; tokens: string[] }[];
+}
+
+export interface CoverageInput {
+  manifest: readonly { namespace: string }[];
+  moduleManifest: readonly { namespace: string }[];
+  unmapped: ReadonlyMap<string, string>;
+  syncedDocs: readonly SyncedDoc[];
+}
+
+export function buildCoverageReport(input: CoverageInput): CoverageReport {
+  const wiredSet = new Set(input.moduleManifest.map((e) => e.namespace));
+  const wired: string[] = [];
+  const fixtureOnly: string[] = [];
+  for (const item of input.manifest) {
+    (wiredSet.has(item.namespace) ? wired : fixtureOnly).push(item.namespace);
+  }
+  const missingMapping = [...input.unmapped.keys()];
+
+  const unknownTypeTokens: { namespace: string; tokens: string[] }[] = [];
+  for (const synced of input.syncedDocs) {
+    const module = parseDefoldApiDoc(synced.doc);
+    const tokens = collectUnknownTokens(module);
+    if (tokens.length > 0) {
+      unknownTypeTokens.push({ namespace: synced.namespace, tokens });
+    }
+  }
+  return { wired, fixtureOnly, missingMapping, unknownTypeTokens };
+}
+
+function collectUnknownTokens(module: ApiModule): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const consider = (types: readonly string[]) => {
+    for (const token of types) {
+      if (Object.hasOwn(DEFOLD_TYPE_MAP, token) || seen.has(token)) continue;
+      seen.add(token);
+      out.push(token);
+    }
+  };
+  for (const fn of module.functions) {
+    for (const param of fn.parameters) consider(param.types);
+    for (const ret of fn.returnValues) consider(ret.types);
+  }
+  for (const variable of module.variables) consider(variable.types);
+  return out;
+}
+
+function printReport(results: FixtureSyncResult[], report: CoverageReport, check: boolean): void {
+  const verb = check ? "checked" : "synced";
+  console.log(`${verb} ${results.length} mapped fixture(s) from Defold ${DEFOLD_VERSION}`);
+  for (const status of ["created", "drift", "clean"] as const) {
+    const names = results.filter((r) => r.status === status).map((r) => r.namespace);
+    if (names.length > 0) console.log(`  ${status}: ${names.join(", ")}`);
+  }
+
+  console.log("\ncoverage");
+  console.log(`  wired (${report.wired.length}): ${report.wired.join(", ")}`);
+  console.log(`  fixture-only (${report.fixtureOnly.length}): ${report.fixtureOnly.join(", ")}`);
+  console.log(
+    `  missing-mapping (${report.missingMapping.length}): ${report.missingMapping.join(", ")}`,
+  );
+
+  if (report.unknownTypeTokens.length > 0) {
+    console.log("\nunknown type tokens (would emit `unknown`)");
+    for (const { namespace, tokens } of report.unknownTypeTokens) {
+      console.log(`  ${namespace}: ${tokens.join(", ")}`);
+    }
+  }
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const check = args.includes("--check");
+  const zipPath = args.find((a) => !a.startsWith("--"));
+  const zip = zipPath ? readZip(zipPath) : await downloadZip();
+
+  const coreFixtures = extractFixtures(zip);
+  const extensionFixtures = await downloadExtensionFixtures();
+  const results = [
+    ...syncExtractedFixtures(coreFixtures, { check }),
+    ...syncExtractedFixtures(extensionFixtures, { check }),
+  ];
+  const syncedDocs = [...coreFixtures, ...extensionFixtures].map((f) => ({
+    namespace: f.namespace,
+    doc: JSON.parse(f.contents),
+  }));
+  const report = buildCoverageReport({
+    manifest: [...SYNC_MANIFEST, ...EXTENSION_MANIFEST],
+    moduleManifest: MODULE_MANIFEST,
+    unmapped: UNMAPPED,
+    syncedDocs,
+  });
+  printReport(results, report, check);
+
+  if (check && results.some((r) => r.status === "drift")) {
+    process.exitCode = 1;
+  }
+}