@defold-typescript/types 0.40.0 → 0.41.0

package/scripts/fidelity-baseline.json

@@ -5,7 +5,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "b2d.body": {
     "droppedElements": 0,
@@ -13,7 +14,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "b2d.chain": {
     "droppedElements": 0,
@@ -21,7 +23,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "b2d.fixture": {
     "droppedElements": 0,
@@ -29,7 +32,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "b2d.joint": {
     "droppedElements": 0,
@@ -37,7 +41,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "b2d.shape": {
     "droppedElements": 0,
@@ -45,7 +50,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "b2d.world": {
     "droppedElements": 0,
@@ -53,7 +59,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "buffer": {
     "droppedElements": 0,
@@ -61,7 +68,62 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
+  },
+  "bullet3d": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
+  },
+  "bullet3d.collision_object": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
+  },
+  "bullet3d.constraint": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
+  },
+  "bullet3d.rigid_body": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
+  },
+  "bullet3d.shape": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
+  },
+  "bullet3d.world": {
+    "droppedElements": 0,
+    "unknownTokens": [],
+    "recordTables": 0,
+    "multiReturn": 0,
+    "droppedMembers": 0,
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "camera": {
     "droppedElements": 0,
@@ -69,7 +131,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "collectionfactory": {
     "droppedElements": 0,
@@ -77,7 +140,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "collectionproxy": {
     "droppedElements": 0,
@@ -85,7 +149,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "compute": {
     "droppedElements": 0,
@@ -93,7 +158,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "crash": {
     "droppedElements": 0,
@@ -101,7 +167,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "factory": {
     "droppedElements": 0,
@@ -109,7 +176,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "font": {
     "droppedElements": 0,
@@ -117,7 +185,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "go": {
     "droppedElements": 0,
@@ -125,7 +194,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "graphics": {
     "droppedElements": 0,
@@ -133,7 +203,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "gui": {
     "droppedElements": 0,
@@ -141,7 +212,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "html5": {
     "droppedElements": 0,
@@ -149,7 +221,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "http": {
     "droppedElements": 0,
@@ -157,7 +230,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "iac": {
     "droppedElements": 0,
@@ -165,7 +239,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "iap": {
     "droppedElements": 0,
@@ -173,7 +248,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "image": {
     "droppedElements": 0,
@@ -181,7 +257,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "json": {
     "droppedElements": 0,
@@ -189,7 +266,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "label": {
     "droppedElements": 0,
@@ -197,7 +275,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "liveupdate": {
     "droppedElements": 0,
@@ -205,7 +284,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "material": {
     "droppedElements": 0,
@@ -213,7 +293,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "model": {
     "droppedElements": 0,
@@ -221,7 +302,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "msg": {
     "droppedElements": 0,
@@ -229,7 +311,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "particlefx": {
     "droppedElements": 0,
@@ -237,7 +320,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "physics": {
     "droppedElements": 0,
@@ -245,7 +329,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "profiler": {
     "droppedElements": 0,
@@ -253,7 +338,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "push": {
     "droppedElements": 0,
@@ -261,7 +347,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "render": {
     "droppedElements": 0,
@@ -269,7 +356,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "resource": {
     "droppedElements": 0,
@@ -277,7 +365,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "socket": {
     "droppedElements": 0,
@@ -285,7 +374,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "sound": {
     "droppedElements": 0,
@@ -293,7 +383,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "sprite": {
     "droppedElements": 0,
@@ -301,7 +392,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "sys": {
     "droppedElements": 0,
@@ -309,7 +401,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "tilemap": {
     "droppedElements": 0,
@@ -317,7 +410,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "timer": {
     "droppedElements": 0,
@@ -325,7 +419,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "types": {
     "droppedElements": 0,
@@ -333,7 +428,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "vmath": {
     "droppedElements": 0,
@@ -341,7 +437,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "webview": {
     "droppedElements": 0,
@@ -349,7 +446,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "window": {
     "droppedElements": 0,
@@ -357,7 +455,8 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   },
   "zlib": {
     "droppedElements": 0,
@@ -365,6 +464,7 @@
     "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 0
+    "optionalAsRequired": 0,
+    "bindingOpen": 0
   }
 }

package/scripts/generate-api-availability.ts

@@ -10,7 +10,23 @@ import {
   type VersionSurface,
   validateAvailability,
 } from "../src/api-availability";
-import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
+import { type ApiModule, parseDefoldApiDoc, withholdOverloads } from "../src/api-doc";
+import {
+  buildIdentityVocabulary,
+  type IdentityCorrections,
+  type IdentityVocabulary,
+} from "../src/api-identity";
+import { correctionPins } from "../src/correction-pins";
+import {
+  CONSTANT_UNION_ALIASES,
+  HAND_DECLARED_OPTIONAL_SLOTS,
+  OPTIONAL_SLOT_CORRECTIONS,
+  PARAM_TYPE_CORRECTIONS,
+  REQUIRED_SLOT_CORRECTIONS,
+  RETURN_TYPE_CORRECTIONS,
+  routeTypeDeclarations,
+} from "../src/emit-dts";
+import { splitTopLevel } from "../src/luals-type-expr";
 import { type ApiTarget, loadApiTargets, loadTargetModules } from "./regen";
 
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
@@ -71,6 +87,56 @@ export function loadMigrationCatalog(path: string = MIGRATIONS_PATH): ApiMigrati
   return raw as ApiMigrationCatalog;
 }
 
+// The emitter's corrections in the form identity applies them.
+export function identityCorrections(): IdentityCorrections {
+  const union = (ts: string): string[] => splitTopLevel(ts, "|").map((arm) => arm.trim());
+  return {
+    optionalSlots: [...OPTIONAL_SLOT_CORRECTIONS.keys(), ...HAND_DECLARED_OPTIONAL_SLOTS.keys()],
+    requiredSlots: [...REQUIRED_SLOT_CORRECTIONS.keys()],
+    parameterCorrections: Object.fromEntries(
+      [...PARAM_TYPE_CORRECTIONS].map(([key, correction]) => [
+        key,
+        {
+          pins: correctionPins(correction),
+          ...(correction.adds === undefined ? {} : { adds: union(correction.adds) }),
+          ...(correction.removes === undefined ? {} : { removes: [...correction.removes] }),
+        },
+      ]),
+    ),
+    returnCorrections: Object.fromEntries(
+      [...RETURN_TYPE_CORRECTIONS].map(([element, correction]) => [
+        element,
+        {
+          pins: correctionPins(correction),
+          replaces: union(correction.ts),
+          ...(correction.slot === undefined ? {} : { slot: correction.slot }),
+        },
+      ]),
+    ),
+    constantFamilies: Object.fromEntries(
+      CONSTANT_UNION_ALIASES.map((alias) => [`${alias.home}.${alias.name}`, alias.members]),
+    ),
+  };
+}
+
+export const IDENTITY_VOCABULARY_PATH = resolve(PACKAGE_ROOT, "identity-vocabulary.json");
+
+// The vocabulary every committed target declares, which the availability
+// identities and every downstream join resolve ref-doc tokens against.
+export function deriveIdentityVocabulary(
+  packageRoot: string = PACKAGE_ROOT,
+  registryPath: string = resolve(packageRoot, "api-targets.json"),
+): IdentityVocabulary {
+  return buildIdentityVocabulary(
+    loadApiTargets(registryPath)
+      .filter((target) => target.source == null)
+      .flatMap((target) =>
+        loadTargetModules(target, packageRoot).map((entry) => parseDefoldApiDoc(entry.doc)),
+      ),
+    identityCorrections(),
+  );
+}
+
 export interface BuildAvailabilityOptions {
   readonly packageRoot?: string;
   readonly registryPath?: string;
@@ -84,23 +150,33 @@ export function buildAvailabilityArtifact(
   const registryPath = options.registryPath ?? resolve(packageRoot, "api-targets.json");
   const targets = loadApiTargets(registryPath);
   const completeTargets = selectCompleteVersionSurfaces(targets);
+  // Routed per target, like regen, so an identity names the namespace whose
+  // declarations export it and routing never carries a symbol across versions.
   const parse = (target: ApiTarget): ApiModule[] =>
-    loadTargetModules(target, packageRoot).map((entry) => parseDefoldApiDoc(entry.doc));
+    routeTypeDeclarations(
+      loadTargetModules(target, packageRoot).map((entry) =>
+        withholdOverloads(parseDefoldApiDoc(entry.doc), entry.skipOverloads ?? []),
+      ),
+    );
   const surfaces: VersionSurface[] = completeTargets.map((target) => ({
     version: versionOf(target),
     modules: parse(target),
   }));
   const versions = surfaces.map((surface) => surface.version);
+  const vocabulary = deriveIdentityVocabulary(packageRoot, registryPath);
 
-  const derived = deriveAvailabilityMatrix({ surfaces });
+  const derived = deriveAvailabilityMatrix({ surfaces, vocabulary });
   const catalog =
     options.catalog ?? loadMigrationCatalog(resolve(packageRoot, "api-migrations.json"));
-  const universe = collectSymbolIdentities(surfaces.flatMap((surface) => surface.modules));
+  const universe = collectSymbolIdentities(
+    surfaces.flatMap((surface) => surface.modules),
+    vocabulary,
+  );
   const records = applyMigrationOverlay({ derived, catalog, universe, versions });
 
   const newestSurface = surfaces[0] as VersionSurface;
   const currentSurface = new Set(
-    collectSymbolIdentities(newestSurface.modules).map(symbolIdentityKey),
+    collectSymbolIdentities(newestSurface.modules, vocabulary).map(symbolIdentityKey),
   );
   const knownIdentities = new Set(universe.map(symbolIdentityKey));
   const errors = validateAvailability({ records, versions, currentSurface, knownIdentities });
@@ -111,13 +187,10 @@ export function buildAvailabilityArtifact(
   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),
-    },
-  );
+function biomeFormatJson(raw: string, name = "api-availability.json"): string {
+  const out = Bun.spawnSync(["bunx", "biome", "format", `--stdin-file-path=${name}`], {
+    stdin: Buffer.from(raw),
+  });
   if (out.exitCode !== 0) {
     throw new Error(`biome format failed: ${out.stderr.toString()}`);
   }
@@ -131,6 +204,11 @@ export function serializeAvailabilityArtifact(artifact: AvailabilityArtifact): s
 if (import.meta.main) {
   const artifact = buildAvailabilityArtifact();
   if (process.argv.includes("--write")) {
+    Bun.write(
+      IDENTITY_VOCABULARY_PATH,
+      biomeFormatJson(JSON.stringify(deriveIdentityVocabulary()), "identity-vocabulary.json"),
+    );
+    console.log(`wrote ${IDENTITY_VOCABULARY_PATH}`);
     Bun.write(AVAILABILITY_PATH, serializeAvailabilityArtifact(artifact));
     console.log(`wrote ${AVAILABILITY_PATH} (${artifact.records.length} records)`);
   } else {

package/scripts/generate-api-signatures.ts

@@ -3,6 +3,7 @@ import { symbolIdentityKey } from "../src/api-availability";
 import type { SlotTypes } from "../src/emit-dts";
 import { selectCompleteVersionSurfaces, versionOf } from "./generate-api-availability";
 import {
+  type ApiTarget,
   generateModuleSignatures,
   loadApiTargets,
   loadTargetModules,
@@ -27,6 +28,10 @@ export interface SignaturesArtifact {
 export interface BuildSignaturesOptions {
   readonly packageRoot?: string;
   readonly registryPath?: string;
+  // The constants each target's engine registers, which gate the undocumented
+  // constant back-fill. Omitted, every target is emitted ungated. Supplied by the
+  // in-repo callers only: the vendored bindings it reads are not published.
+  readonly registeredConstantsOf?: (target: ApiTarget) => ReadonlySet<string> | undefined;
 }
 
 // The authored replacement for a symbol the skip filter withheld, read from the
@@ -74,8 +79,12 @@ export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): S
     const version = versionOf(target);
     const perSymbol: Record<string, string> = {};
     const perSymbolSlots: Record<string, SlotTypes> = {};
+    const registeredConstants = options.registeredConstantsOf?.(target);
     for (const entry of loadTargetModules(target, packageRoot)) {
-      for (const signature of generateModuleSignatures(entry)) {
+      for (const signature of generateModuleSignatures(
+        entry,
+        registeredConstants ? { registeredConstants } : undefined,
+      )) {
         const key = symbolIdentityKey(signature.identity);
         perSymbol[key] = signature.tsSignature;
         if (Object.keys(signature.slotTypes).length > 0) {
@@ -120,7 +129,8 @@ export function serializeSignaturesArtifact(artifact: SignaturesArtifact): strin
 }
 
 if (import.meta.main) {
-  const artifact = buildSignaturesArtifact();
+  const { registeredConstantFqns } = await import("./engine-binding-extract");
+  const artifact = buildSignaturesArtifact({ registeredConstantsOf: registeredConstantFqns });
   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);