@defold-typescript/types 0.48.0 → 0.50.0

package/scripts/import-defold-release.ts

@@ -7,6 +7,7 @@ import {
   EDITOR_MANIFEST,
   type ExtractedFixture,
   extractAnnotationFixtures,
+  groupDocsByNamespace,
   IGNORED_UPSTREAM,
   mergeApiDocs,
   readZip,
@@ -15,7 +16,6 @@ import {
 } from "./sync-api-docs";
 
 const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
-const LUA_NAMESPACE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 const DECLARED_NAME_KINDS = new Set(["CONSTANT", "ENUM", "STRUCT", "TYPEDEF", "CLASS"]);
 const PACKAGE_ROOT = resolve(import.meta.dir, "..");
 
@@ -75,11 +75,6 @@ interface RawElement extends Record<string, unknown> {
   name?: string;
 }
 
-interface RawApiDoc extends Record<string, unknown> {
-  info?: { namespace?: string };
-  elements?: RawElement[];
-}
-
 export interface ReleaseBaselineModule {
   readonly namespace: string;
   readonly fixture: string;
@@ -177,20 +172,6 @@ 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[];
@@ -297,16 +278,7 @@ export function buildReleaseImportPlan(input: {
     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 grouped = groupDocsByNamespace(input.zip);
 
   const baselineModules = [...input.baseline.modules, ...input.baseline.luaStdlib];
   const generatedNamespaces = new Set(input.baseline.modules.map((module) => module.namespace));
@@ -319,7 +291,7 @@ export function buildReleaseImportPlan(input: {
   };
 
   const sources: ReleaseSource[] = incomingNamespaces.map((namespace) => {
-    const group = grouped.get(namespace) as Array<{ entry: string; doc: RawApiDoc }>;
+    const group = grouped.get(namespace) ?? [];
     return {
       namespace,
       entries: group.map(({ entry }) => entry).sort(),

package/scripts/materialize-version.ts

@@ -11,6 +11,7 @@ import {
   loadSrcAugmentations,
   loadTargetEditorModules,
   MESSAGES_MANIFEST,
+  type ModuleManifestEntry,
   type ResolveTargetOptions,
   resolveTargetModules,
 } from "./regen";
@@ -138,13 +139,18 @@ export async function buildVersionedSurfaceFiles(
     opts.augmentations ?? loadSrcAugmentations(opts.resolveOpts?.packageRoot ?? undefined)
   ).filter((file) => kept(file.path));
 
-  const files: VersionedSurfaceFile[] = [...modules, ...editorModules].map((entry) => ({
-    path: entry.outFile,
-    contents: generateModuleDeclaration({
-      ...entry,
-      importsFrom: surfaceCoreTypesImport(entry.outFile),
-    }).contents,
-  }));
+  // Re-rooting an entry makes it a new object no committed manifest holds, so
+  // each lane is handed to the emit as the surface it routes: a type one module
+  // declares for another, or names from another, resolves only across the set.
+  const rerooted = (entries: readonly ModuleManifestEntry[]): ModuleManifestEntry[] =>
+    entries.map((entry) => ({ ...entry, importsFrom: surfaceCoreTypesImport(entry.outFile) }));
+  const files: VersionedSurfaceFile[] = [rerooted(modules), rerooted(editorModules)].flatMap(
+    (surface) =>
+      surface.map((entry) => ({
+        path: entry.outFile,
+        contents: generateModuleDeclaration(entry, { surface }).contents,
+      })),
+  );
 
   files.push(...augmentations);
   files.push({ path: "core-types.d.ts", contents: CORE_TYPES_REEXPORT });

package/scripts/regen.ts

@@ -42,7 +42,7 @@ import {
 import { loadTranslations } from "./example-store-io";
 import { synthesizeProseConstants } from "./prose-constants";
 import { restoreSharedHandleMethods } from "./shared-handle-methods";
-import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
+import { groupDocsByNamespace, mergeApiDocs, type readZip } from "./sync-api-docs";
 
 export interface ApiTargetModule {
   readonly namespace: string;
@@ -120,6 +120,12 @@ function withSkipRules(entry: ModuleManifestEntry, module: ApiTargetModule): Mod
   };
 }
 
+// Shared by both module sources: a step applied in one branch alone gives a
+// ref-doc surface different members from a committed one.
+function restoreOmittedMembers(modules: readonly ModuleManifestEntry[]): ModuleManifestEntry[] {
+  return restoreSharedHandleMethods(synthesizeProseConstants(modules));
+}
+
 export function loadTargetModules(
   target: ApiTarget,
   packageRoot: string = PACKAGE_ROOT,
@@ -142,7 +148,7 @@ export function loadTargetModules(
     };
     return withSkipRules(entry, module);
   });
-  return restoreSharedHandleMethods(synthesizeProseConstants(modules));
+  return restoreOmittedMembers(modules);
 }
 
 export interface ModuleManifestEntry {
@@ -174,7 +180,6 @@ export interface ResolveTargetOptions {
   readonly cacheDir?: string;
   readonly download?: DownloadRefDoc;
   readonly readZip?: typeof readZip;
-  readonly syncManifest?: readonly SyncManifestEntry[];
   readonly packageRoot?: string;
   readonly channel?: RefDocChannel;
   readonly fetchChannelInfo?: FetchChannelInfo;
@@ -182,8 +187,8 @@ export interface ResolveTargetOptions {
 
 // 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.
+// resolves its docs on demand from the version's ref-doc zip, reading every
+// doc the zip declares for the namespace, merged.
 export async function resolveTargetModules(
   target: ApiTarget,
   opts: ResolveTargetOptions = {},
@@ -200,24 +205,24 @@ export async function resolveTargetModules(
     ...(opts.readZip ? { readZip: opts.readZip } : {}),
     ...(opts.fetchChannelInfo ? { fetchChannelInfo: opts.fetchChannelInfo } : {}),
   });
-  const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
+  const grouped = groupDocsByNamespace(zip);
   const modules = target.modules.map((module) => {
-    const sync = syncManifest.find((s) => s.namespace === module.namespace);
-    if (!sync) {
+    const group = grouped.get(module.namespace);
+    if (!group) {
       throw new Error(
-        `api-targets.json: target "${target.id}" module "${module.namespace}": no SYNC_MANIFEST zip entry`,
+        `api-targets.json: target "${target.id}" module "${module.namespace}": no doc in the ref-doc zip declares this namespace`,
       );
     }
     const entry: ModuleManifestEntry = {
       namespace: module.namespace,
-      doc: JSON.parse(zip.read(sync.zipEntry)),
+      doc: mergeApiDocs(group.map((item) => item.doc)),
       outFile: module.outFile,
       importsFrom: target.coreTypesImport,
       sourceProvenance: provenance,
     };
     return withSkipRules(entry, module);
   });
-  return synthesizeProseConstants(modules);
+  return restoreOmittedMembers(modules);
 }
 
 const API_TARGETS = loadApiTargets();
@@ -451,6 +456,10 @@ export interface GenerateOptions {
   translations?: TranslationStore;
   urlParameters?: UrlParameterTable;
   registeredConstants?: ReadonlySet<string>;
+  // The modules the entry is emitted beside, the entry among them. Routing
+  // reads this set instead of looking the entry up in a committed manifest, so
+  // a surface built with its own import root still routes as a whole.
+  surface?: readonly ModuleManifestEntry[];
 }
 
 interface PreparedGeneratedModule {
@@ -472,7 +481,7 @@ function prepareGeneratedModule(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): PreparedGeneratedModule {
-  const routed = routedModuleOf(entry);
+  const routed = routedModuleOf(entry, options?.surface);
   const { module, dropped } = routed?.prepared ?? withheldApiModule(entry);
   const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
   const translations = options?.translations ?? loadTranslations();
@@ -495,36 +504,61 @@ interface RoutedSurface {
 }
 
 const routedSurfaces = new Map<string, RoutedSurface>();
+const routedCallerSurfaces = new WeakMap<readonly ModuleManifestEntry[], RoutedSurface>();
+
+function routeSurface(entries: readonly ModuleManifestEntry[]): RoutedSurface {
+  const withheld = entries.map(withheldApiModule);
+  const routed = routeTypeDeclarations(withheld.map(({ module }) => module));
+  return {
+    modules: new Map(
+      entries.map((member, index) => [
+        member,
+        {
+          module: routed[index] as ApiModule,
+          dropped: (withheld[index] as { dropped: string[] }).dropped,
+        },
+      ]),
+    ),
+    declaredTypes: declaredTypePaths(routed),
+  };
+}
 
 // A doc may declare a type another module owns (`b2d.joint.revolute_definition`
 // in the `b2d` doc) or name one another doc declares (`material.constant_info`
 // in `compute`), so each committed surface is routed as a whole: the runtime
-// modules and the editor modules of one target, never across targets. An entry
-// outside every committed manifest routes alone, as a single-module surface.
-function routedModuleOf(entry: ModuleManifestEntry):
+// modules and the editor modules of one target, never across targets. A caller
+// that names its own surface routes that set instead. An entry with neither, and
+// outside every committed manifest, routes alone, as a single-module surface.
+function routedModuleOf(
+  entry: ModuleManifestEntry,
+  callerSurface?: readonly ModuleManifestEntry[],
+):
   | {
       prepared: { module: ApiModule; dropped: string[] };
       declaredTypes: ReadonlyMap<string, string>;
     }
   | undefined {
+  if (callerSurface !== undefined) {
+    let surface = routedCallerSurfaces.get(callerSurface);
+    if (surface === undefined) {
+      surface = routeSurface(callerSurface);
+      routedCallerSurfaces.set(callerSurface, surface);
+    }
+    const prepared = surface.modules.get(entry);
+    // Falling back to a lone module here would emit `unknown` for every type a
+    // sibling declares, which type-checks and so goes unnoticed.
+    if (prepared === undefined) {
+      throw new Error(
+        `module "${entry.namespace}" is not a member of the surface it is emitted in`,
+      );
+    }
+    return { prepared, declaredTypes: surface.declaredTypes };
+  }
   const located = committedSurfaceOf(entry);
   if (located === undefined) return undefined;
   let surface = routedSurfaces.get(located.key);
   if (surface === undefined) {
-    const withheld = located.entries.map(withheldApiModule);
-    const routed = routeTypeDeclarations(withheld.map(({ module }) => module));
-    surface = {
-      modules: new Map(
-        located.entries.map((member, index) => [
-          member,
-          {
-            module: routed[index] as ApiModule,
-            dropped: (withheld[index] as { dropped: string[] }).dropped,
-          },
-        ]),
-      ),
-      declaredTypes: declaredTypePaths(routed),
-    };
+    surface = routeSurface(located.entries);
     routedSurfaces.set(located.key, surface);
   }
   const prepared = surface.modules.get(located.member);

package/scripts/sync-api-docs.ts

@@ -11,7 +11,7 @@ import { MODULE_MANIFEST } from "./regen";
 // model because the per-package `rootDir` boundary forbids a types-package
 // module importing outside its own tree; `scripts/release-model.test.ts`
 // correspondence-guards these against the model so drift fails CI.
-export const DEFOLD_VERSION = "1.13.2";
+export const DEFOLD_VERSION = "1.14.0";
 export const refDocUrl = (version = DEFOLD_VERSION): string =>
   `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
 
@@ -216,7 +216,7 @@ function editorVm(namespace: string): SyncManifestEntry {
 function entry(
   namespace: string,
   zipEntry: string,
-  fixture: string = `fixtures/defold-1.13.2/${namespace.replace(/\./g, "_")}_doc.json`,
+  fixture: string = `fixtures/defold-1.14.0/${namespace.replace(/\./g, "_")}_doc.json`,
   mergeEntries?: readonly string[],
 ): SyncManifestEntry {
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
@@ -538,6 +538,35 @@ export interface CoverageInput {
   ignoredUpstream?: ReadonlyMap<string, string>;
 }
 
+// The Lua docs of a zip, grouped by the namespace each one declares. Entry names
+// belong to one release (`label` is one entry in 1.9.8 and two in 1.14.0), so
+// the declared namespace picks the docs. Entries are read in sorted order
+// because `mergeApiDocs` keeps the first doc's `info` and the docs' element
+// order; only `.json` entries are read because each read of a real zip is one
+// `unzip -p` process.
+export function groupDocsByNamespace(
+  zip: ZipAccessor,
+): Map<string, { entry: string; doc: Record<string, unknown> }[]> {
+  const grouped = new Map<string, { entry: string; doc: Record<string, unknown> }[]>();
+  for (const entry of [...zip.entries()].sort()) {
+    if (!entry.endsWith(".json")) continue;
+    const raw = zip.read(entry);
+    let doc: unknown;
+    try {
+      doc = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!isRecord(doc)) continue;
+    const namespace = isRecord(doc.info) ? doc.info.namespace : undefined;
+    if (typeof namespace !== "string" || !LUA_NAMESPACE.test(namespace)) continue;
+    const group = grouped.get(namespace) ?? [];
+    group.push({ entry, doc });
+    grouped.set(namespace, group);
+  }
+  return grouped;
+}
+
 // Enumerate every `doc/*.json` zip entry, reading its `info.namespace` and the
 // count of FUNCTION elements. Only function-bearing docs are returned, so
 // message-only / struct-only docs never reach the coverage guard.

package/src/emit-dts.ts

@@ -5639,6 +5639,27 @@ function unionFromTokens(tokens: readonly string[], mapType: DefoldTypeMapper):
 }
 
 const BRAND_ARM = /^(?:number|string) & \{ readonly __brand: "([^"]+)" \}$/;
+const OPAQUE_ARM = /^Opaque<("[^"]+"(?: \| "[^"]+")*)>$/;
+
+// Drops each `Opaque` arm whose brands are a proper subset of another `Opaque`
+// arm's. `Opaque<Name>` holds `Name` in one readonly property, so a narrower
+// brand set is assignable to a wider one and the narrower arm adds nothing.
+// An arm of any other shape (`Opaque<"x">[]`, an intersection) is never dropped
+// and never causes a drop.
+function withoutSubsumedOpaqueArms(mapped: readonly string[]): string[] {
+  const brandSets = mapped.map((arm) => {
+    const match = OPAQUE_ARM.exec(arm);
+    return match === null ? undefined : new Set((match[1] as string).split(" | "));
+  });
+  return mapped.filter((_, index) => {
+    const own = brandSets[index];
+    if (own === undefined) return true;
+    return !brandSets.some(
+      (other) =>
+        other !== undefined && other.size > own.size && [...own].every((b) => other.has(b)),
+    );
+  });
+}
 
 // Joins already-mapped arms, collapsing the branded ones to their alias when
 // they are exactly a `CONSTANT_UNION_ALIASES` member set. The alias takes the
@@ -5646,16 +5667,17 @@ const BRAND_ARM = /^(?:number|string) & \{ readonly __brand: "([^"]+)" \}$/;
 // (`gui.Easing | Vector`). Arms that are not constants are untouched, and a set
 // with no row keeps every arm inline.
 function joinUnionArms(mapped: readonly string[]): string {
+  const arms = withoutSubsumedOpaqueArms(mapped);
   const branded: string[] = [];
-  for (const arm of mapped) {
+  for (const arm of arms) {
     const match = BRAND_ARM.exec(arm);
     if (match !== null) branded.push(match[1] as string);
   }
   const alias = constantUnionAlias(branded);
-  if (alias === undefined) return mapped.join(" | ");
+  if (alias === undefined) return arms.join(" | ");
   const out: string[] = [];
   let placed = false;
-  for (const arm of mapped) {
+  for (const arm of arms) {
     if (BRAND_ARM.test(arm)) {
       if (placed) continue;
       out.push(`${alias.home}.${alias.name}`);