@defold-typescript/types 0.50.1 → 0.52.0

package/scripts/generate-api-availability.ts

@@ -28,37 +28,17 @@ import {
 } from "../src/emit-dts";
 import { splitTopLevel } from "../src/luals-type-expr";
 import { type ApiTarget, loadApiTargets, loadTargetModules } from "./regen";
+import { compareVersions, versionOf } from "./target-version";
 
 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
@@ -108,7 +88,11 @@ export function identityCorrections(): IdentityCorrections {
         element,
         {
           pins: correctionPins(correction),
-          replaces: union(correction.ts),
+          ...(correction.ts !== undefined
+            ? { replaces: union(correction.ts) }
+            : correction.nullable
+              ? { adds: ["nil"] }
+              : { removes: ["nil"] }),
           ...(correction.slot === undefined ? {} : { slot: correction.slot }),
         },
       ]),

package/scripts/generate-api-signatures.ts

@@ -1,15 +1,18 @@
 import { resolve } from "node:path";
 import { symbolIdentityKey } from "../src/api-availability";
-import type { SlotTypes } from "../src/emit-dts";
-import { selectCompleteVersionSurfaces, versionOf } from "./generate-api-availability";
+import type { SlotType, SlotTypes } from "../src/emit-dts";
+import { signatureArmsFor } from "../src/signature-store";
+import { selectCompleteVersionSurfaces } from "./generate-api-availability";
 import {
   type ApiTarget,
   generateModuleSignatures,
   loadApiTargets,
   loadTargetModules,
   type ModuleManifestEntry,
+  type TargetBindingOptions,
 } from "./regen";
 import { loadSignatureFile } from "./signature-store-fs";
+import { versionOf } from "./target-version";
 
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 const SIGNATURES_PATH = resolve(PACKAGE_ROOT, "api-signatures.json");
@@ -28,10 +31,13 @@ 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;
+  // What each target's engine source decides for its emit (`targetBindingOptions`):
+  // the constants it registers, which gate the undocumented constant back-fill,
+  // and the binding-pinned return corrections whose pin holds there. Omitted,
+  // every target is emitted ungated and with no binding-pinned correction.
+  // Supplied by the in-repo callers only: the vendored bindings it reads are not
+  // published.
+  readonly emitOptionsOf?: (target: ApiTarget) => TargetBindingOptions;
 }
 
 // The authored replacement for a symbol the skip filter withheld, read from the
@@ -39,22 +45,59 @@ export interface BuildSignaturesOptions {
 // One seam keeps all three artifacts consistent: `overloads-signature-parity`
 // pins the store to the `src/*-overloads.d.ts` declarations, so folding the
 // store in cannot drift from the surface a consumer actually compiles against.
-function authoredSignature(packageRoot: string, namespace: string, fqn: string): string | null {
+// Only the arms the target's version declares are folded.
+function authoredSignature(
+  packageRoot: string,
+  namespace: string,
+  fqn: string,
+  version: string,
+): string | null {
   const store = loadSignatureFile(resolve(packageRoot, "signatures", `${namespace}.json`));
-  const forms = store[fqn]?.signatures ?? [];
+  const override = store[fqn];
+  const forms = override ? signatureArmsFor(override, version).signatures : [];
   return forms.length > 0 ? forms.join("\n") : null;
 }
 
+interface UnfilteredSurface {
+  readonly entries: readonly ModuleManifestEntry[];
+  readonly of: ReadonlyMap<ModuleManifestEntry, ModuleManifestEntry>;
+}
+
+const unfilteredSurfaces = new WeakMap<readonly ModuleManifestEntry[], UnfilteredSurface>();
+
+// The surface with every member's `skipFunctions` cleared, built once per
+// surface: dropping functions moves no type declaration, so it routes exactly
+// as the filtered one does.
+function unfilteredSurfaceOf(surface: readonly ModuleManifestEntry[]): UnfilteredSurface {
+  let unfiltered = unfilteredSurfaces.get(surface);
+  if (unfiltered === undefined) {
+    const of = new Map(surface.map((member) => [member, { ...member, skipFunctions: [] }]));
+    unfiltered = { entries: [...of.values()], of };
+    unfilteredSurfaces.set(surface, unfiltered);
+  }
+  return unfiltered;
+}
+
 // The symbols `skipFunctions` removed from this module, as the difference
 // between the unfiltered and filtered signature emits. Derived rather than
 // re-matched so the withholding rules stay owned by `prepareGeneratedModule`.
-export function withheldSymbols(entry: ModuleManifestEntry): { key: string; fqn: string }[] {
+// Both emits route in `surface`, the modules the entry is emitted beside, so a
+// slot naming a sibling's type resolves in the unfiltered emit too.
+export function withheldSymbols(
+  entry: ModuleManifestEntry,
+  surface: readonly ModuleManifestEntry[],
+): { key: string; fqn: string }[] {
   if ((entry.skipFunctions ?? []).length === 0) return [];
   const kept = new Set(
-    generateModuleSignatures(entry).map(({ identity }) => symbolIdentityKey(identity)),
+    generateModuleSignatures(entry, { surface }).map(({ identity }) => symbolIdentityKey(identity)),
   );
+  const unfiltered = unfilteredSurfaceOf(surface);
+  const self = unfiltered.of.get(entry);
+  if (self === undefined) {
+    throw new Error(`module "${entry.namespace}" is not a member of the surface it is emitted in`);
+  }
   const withheld: { key: string; fqn: string }[] = [];
-  for (const { identity } of generateModuleSignatures({ ...entry, skipFunctions: [] })) {
+  for (const { identity } of generateModuleSignatures(self, { surface: unfiltered.entries })) {
     const key = symbolIdentityKey(identity);
     if (kept.has(key)) continue;
     const fqn = key.split("\0")[2] as string;
@@ -63,6 +106,18 @@ export function withheldSymbols(entry: ModuleManifestEntry): { key: string; fqn:
   return withheld;
 }
 
+// The slots two arms record identically. One ledger cannot describe arms whose
+// types differ at a slot, so that slot is dropped and its row falls back to the
+// ref-doc token.
+function commonSlots(a: SlotTypes, b: SlotTypes): SlotTypes {
+  const common: Record<string, SlotType> = {};
+  for (const [slot, record] of Object.entries(a)) {
+    const other = b[slot];
+    if (other?.type === record.type && other.optional === record.optional) common[slot] = record;
+  }
+  return common;
+}
+
 function sortObjectKeys<T>(record: Record<string, T>): Record<string, T> {
   const sorted: Record<string, T> = {};
   for (const key of Object.keys(record).sort()) sorted[key] = record[key] as T;
@@ -79,13 +134,22 @@ 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,
-        registeredConstants ? { registeredConstants } : undefined,
-      )) {
+    const emitOptions = options.emitOptionsOf?.(target);
+    const surface = loadTargetModules(target, packageRoot);
+    for (const entry of surface) {
+      for (const signature of generateModuleSignatures(entry, emitOptions)) {
         const key = symbolIdentityKey(signature.identity);
+        // Two ref-doc elements can normalize to one identity (the Box2D backend
+        // forms of a `b2d.world` query), so each keeps its arms in fixture order
+        // and the key keeps only the slots every arm shares.
+        const earlier = perSymbol[key];
+        if (earlier !== undefined) {
+          perSymbol[key] = `${earlier}\n${signature.tsSignature}`;
+          const common = commonSlots(perSymbolSlots[key] ?? {}, signature.slotTypes);
+          if (Object.keys(common).length > 0) perSymbolSlots[key] = common;
+          else delete perSymbolSlots[key];
+          continue;
+        }
         perSymbol[key] = signature.tsSignature;
         if (Object.keys(signature.slotTypes).length > 0) {
           perSymbolSlots[key] = sortObjectKeys({ ...signature.slotTypes });
@@ -93,8 +157,8 @@ export function buildSignaturesArtifact(options: BuildSignaturesOptions = {}): S
       }
       // An authored fold replaces the declaration text wholesale, so whatever
       // slots the generated emit had recorded no longer describe it.
-      for (const { key, fqn } of withheldSymbols(entry)) {
-        const authored = authoredSignature(packageRoot, entry.namespace, fqn);
+      for (const { key, fqn } of withheldSymbols(entry, surface)) {
+        const authored = authoredSignature(packageRoot, entry.namespace, fqn, version);
         if (authored !== null) {
           perSymbol[key] = authored;
           delete perSymbolSlots[key];
@@ -129,8 +193,10 @@ export function serializeSignaturesArtifact(artifact: SignaturesArtifact): strin
 }
 
 if (import.meta.main) {
-  const { registeredConstantFqns } = await import("./engine-binding-extract");
-  const artifact = buildSignaturesArtifact({ registeredConstantsOf: registeredConstantFqns });
+  const { targetBindingOptions } = await import("./binding-pin");
+  const artifact = buildSignaturesArtifact({
+    emitOptionsOf: (target) => targetBindingOptions(target),
+  });
   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);

package/scripts/materialize-version.ts

@@ -2,18 +2,23 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import {
   type ApiTarget,
+  GO_INSTANCE_SRC_AUGMENTATIONS,
   generateBuiltinMessagesDeclaration,
   generateModuleDeclaration,
   generateVersionIndex,
+  goInstanceFreeSurface,
+  goInstanceWalls,
   KIND_MODULE_MANIFEST,
   type KindManifestEntry,
   kindStdlibReferences,
+  loadGoInstanceFunctions,
   loadSrcAugmentations,
   loadTargetEditorModules,
   MESSAGES_MANIFEST,
   type ModuleManifestEntry,
   type ResolveTargetOptions,
   resolveTargetModules,
+  type TargetBindingOptions,
 } from "./regen";
 
 export {
@@ -40,6 +45,11 @@ export interface RenderMaterializedKindIndexOptions {
   // the universal set outright — an editor kind is disjoint from the runtime
   // surface, not a narrowing of it.
   readonly editorModules?: readonly string[];
+  // The universal modules the surface also carries as copies without the
+  // functions that need a game object, set when the target records which those
+  // are. A kind with no game object imports the copies instead and drops the
+  // augmentations marked as needing one; every other kind ignores it.
+  readonly goInstanceFreeModules?: readonly string[];
 }
 
 // The installed subpath a materialized kind re-exports its factory from: the
@@ -56,11 +66,21 @@ function installedFactoryModule(entry: KindManifestEntry): string {
 export function renderMaterializedKindIndex(opts: RenderMaterializedKindIndexOptions): string {
   const entry = KIND_MODULE_MANIFEST.find((e) => e.kind === opts.kind);
   if (!entry) throw new Error(`unknown script kind: ${opts.kind}`);
+  const freeDir = entry.goInstanceFreeDir;
+  const copied =
+    freeDir === undefined || opts.goInstanceFreeModules === undefined
+      ? null
+      : new Set(opts.goInstanceFreeModules);
+  const universal = opts.universalModules.filter(
+    (mod) => copied === null || !GO_INSTANCE_SRC_AUGMENTATIONS.includes(mod),
+  );
   const modules =
     entry.only === undefined
-      ? [...new Set(["engine-globals", ...opts.universalModules])].sort()
+      ? [...new Set(["engine-globals", ...universal])].sort()
       : [...(opts.editorModules ?? [])];
-  const lines = modules.map((mod) => `import "../${mod}";`);
+  const lines = modules.map((mod) =>
+    copied?.has(mod) ? `import "../${freeDir}/${mod}";` : `import "../${mod}";`,
+  );
   if (entry.only === undefined && opts.restrictedModule) {
     lines.push(`import "../${opts.restrictedModule}";`);
   }
@@ -88,9 +108,15 @@ export interface BuildVersionedSurfaceOptions {
   // script kind without the generator knowing what a script kind is.
   readonly excludeModules?: readonly string[];
   // The hand-authored `src/*` augmentations to carry beside the modules.
-  // Defaults to reading them from the types package on disk; a caller with no
-  // filesystem (a Worker) supplies the bytes and gets an identical file map.
+  // Defaults to reading the target's set (`srcAugmentationModulesFor`) from the
+  // types package on disk; a caller with no filesystem (a Worker) supplies the
+  // same bytes and gets an identical file map.
   readonly augmentations?: readonly VersionedSurfaceFile[];
+  // What the target's own engine source decides for its emit
+  // (`targetBindingOptions`). Only an in-repo caller rebuilding a vendored
+  // target's committed surface passes it; a published install vendors no engine
+  // source, and the ref-doc targets it materializes have none to read.
+  readonly emitOptions?: TargetBindingOptions;
 }
 
 export interface MaterializeVersionedSurfaceOptions extends BuildVersionedSurfaceOptions {
@@ -136,7 +162,7 @@ export async function buildVersionedSurfaceFiles(
   ).filter((entry) => kept(entry.outFile));
 
   const augmentations = (
-    opts.augmentations ?? loadSrcAugmentations(opts.resolveOpts?.packageRoot ?? undefined)
+    opts.augmentations ?? loadSrcAugmentations(opts.resolveOpts?.packageRoot ?? undefined, target)
   ).filter((file) => kept(file.path));
 
   // Re-rooting an entry makes it a new object no committed manifest holds, so
@@ -148,10 +174,31 @@ export async function buildVersionedSurfaceFiles(
     (surface) =>
       surface.map((entry) => ({
         path: entry.outFile,
-        contents: generateModuleDeclaration(entry, { surface }).contents,
+        contents: generateModuleDeclaration(entry, { ...opts.emitOptions, surface }).contents,
       })),
   );
 
+  // A target whose engine source records the functions that need a game object
+  // carries, for each kind without one, copies of the modules declaring them
+  // with those functions withheld. Nothing else differs, so a target with no
+  // record writes no copy.
+  const walls = goInstanceWalls(
+    modules,
+    loadGoInstanceFunctions(target, opts.resolveOpts?.packageRoot ?? undefined),
+  );
+  for (const kind of KIND_MODULE_MANIFEST) {
+    const dir = kind.goInstanceFreeDir;
+    if (dir === undefined || walls.size === 0) continue;
+    const surface = rerooted(goInstanceFreeSurface(modules, walls, dir).surface);
+    for (const entry of surface) {
+      if (!entry.outFile.startsWith(`${dir}/`)) continue;
+      files.push({
+        path: entry.outFile,
+        contents: generateModuleDeclaration(entry, { ...opts.emitOptions, surface }).contents,
+      });
+    }
+  }
+
   files.push(...augmentations);
   files.push({ path: "core-types.d.ts", contents: CORE_TYPES_REEXPORT });