@defold-typescript/library-types 0.22.0 → 0.24.0

package/scripts/emit-library-dts.ts

@@ -15,7 +15,12 @@
  * `name` is scoped into a child `MapContext` (an identity rename) so a bare `T`
  * resolves to `T` instead of lowering to `unknown`, constraints and `extends`
  * targets map through the existing rename map, and an `extends` clause is emitted
- * only for parents that resolve to a declared interface.
+ * only for parents that resolve to a declared interface or an imported external type.
+ *
+ * A token owned by another target is declared through `externalTypes`: the emitter
+ * writes a real `import { <name> } from '<module>';` into the `declare module` block
+ * and resolves the token to that binding, so a cross-library reference carries its
+ * real type instead of lowering to `unknown`.
  */
 
 import {
@@ -26,13 +31,16 @@ import {
   varargElementType,
 } from "@defold-typescript/types";
 import {
+  LUALS_VARARG_TOKEN,
   type MapContext,
+  mapLualsCallSignature,
   mapLualsType,
   matchSelfHookField,
   scopeGenerics,
 } from "./map-luals-types";
 import type {
   LibraryAlias,
+  LibraryField,
   LibraryGeneric,
   LibraryInterface,
   LibraryMethod,
@@ -40,13 +48,38 @@ import type {
   LibraryParam,
 } from "./parse-luals";
 
+/**
+ * A type token owned by another target: the module id that declares it and the name
+ * it exports. Resolving one emits a real `import` into the `declare module` block
+ * rather than lowering the token to `unknown`.
+ */
+export interface ExternalTypeRef {
+  module: string;
+  name: string;
+}
+
 export interface EmitLibraryOptions {
   moduleId: string;
   typeRenames?: Record<string, string>;
+  externalTypes?: Record<string, ExternalTypeRef> | undefined;
 }
 
 const INDENT = "\t";
 
+// A member with an explicit non-public visibility is internal surface; keep only
+// members with no visibility or an explicit `public`, mirroring how LuaLS hides
+// `private`/`protected`/`package` (and, for methods, `local`) from a class's public
+// shape. Shared by all three consumers — the emitter, the api-doc lowering, and the
+// fidelity report — so the declaration, documentation, and coverage surfaces
+// describe one identical public member set.
+export function isPublicField(field: LibraryField): boolean {
+  return field.visibility === undefined || field.visibility === "public";
+}
+
+export function isPublicMethod(method: LibraryMethod): boolean {
+  return method.visibility === undefined || method.visibility === "public";
+}
+
 /** A model type name (dotted like `druid.button`) reduced to a legal TS identifier. */
 export function sanitizeTypeName(name: string): string {
   const cleaned = name.replace(/[^A-Za-z0-9_$]/g, "_");
@@ -69,6 +102,42 @@ function safeParamName(name: string, index: number): string {
   return TS_RESERVED_NAMES.has(name) ? `${name}_` : name;
 }
 
+/**
+ * The token -> local-alias rename map an `externalTypes` config contributes, aliasing
+ * exactly as a declared name would (dotted `event.foo` -> `event_foo`). Shared by the
+ * emitter, the fidelity report, and the api-doc lowering so all three resolve an
+ * external reference to the same identifier the import binds.
+ */
+export function externalTypeRenames(
+  externalTypes?: Record<string, ExternalTypeRef>,
+): Record<string, string> {
+  const renames: Record<string, string> = {};
+  for (const token of Object.keys(externalTypes ?? {})) renames[token] = sanitizeTypeName(token);
+  return renames;
+}
+
+/**
+ * `import { ... } from '<module>';` lines for the external tokens, one per source
+ * module with its names sorted and the modules sorted by id, so re-rendering is
+ * byte-identical. A token whose local alias differs from the export name binds
+ * through an `as` clause.
+ */
+function renderExternalImports(externalTypes?: Record<string, ExternalTypeRef>): string[] {
+  const byModule = new Map<string, Set<string>>();
+  for (const [token, ref] of Object.entries(externalTypes ?? {})) {
+    const alias = sanitizeTypeName(token);
+    const binding = alias === ref.name ? ref.name : `${ref.name} as ${alias}`;
+    const names = byModule.get(ref.module) ?? new Set<string>();
+    names.add(binding);
+    byModule.set(ref.module, names);
+  }
+  return [...byModule.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : 1))
+    .map(
+      ([module, names]) => `${INDENT}import { ${[...names].sort().join(", ")} } from '${module}';`,
+    );
+}
+
 export function mapTypes(types: readonly string[], ctx: MapContext): string {
   if (types.length === 0) return "unknown";
   return types.map((token) => mapLualsType(token, ctx).ts).join(" | ");
@@ -91,36 +160,67 @@ export function renderGenericParams(generics: readonly LibraryGeneric[], ctx: Ma
 function renderHookReturn(returnTokens: readonly string[], ctx: MapContext): string {
   if (returnTokens.length === 0) return "void";
   if (returnTokens.length === 1) return mapTypes([returnTokens[0] as string], ctx);
-  return luaMultiReturn(returnTokens.map((token) => mapTypes([token], ctx)));
+  return luaMultiReturn(
+    returnTokens.map((token) => mapTypes([token], ctx)),
+    returnTokens.at(-1) === LUALS_VARARG_TOKEN,
+  );
 }
 
 /**
  * An ` extends X, Y` clause built from `iface.extends` split on commas, keeping only
- * parents that name a declared interface (so no `extends unknown` is ever emitted),
- * mapped through the rename map; `""` when none survive.
+ * parents that name a declared interface or an imported external type (so no
+ * `extends unknown` is ever emitted), mapped through the rename map; `""` when none
+ * survive.
  */
 function renderExtends(
   iface: LibraryInterface,
   ctx: MapContext,
   interfaceNames: ReadonlySet<string>,
+  externalTokens: ReadonlySet<string>,
 ): string {
   if (!iface.extends) return "";
   const parents = iface.extends
     .split(",")
     .map((name) => name.trim())
-    .filter((name) => interfaceNames.has(name))
+    .filter((name) => interfaceNames.has(name) || externalTokens.has(name))
     .map((name) => mapTypes([name], ctx));
   return parents.length > 0 ? ` extends ${parents.join(", ")}` : "";
 }
 
+/**
+ * Which non-vararg params may be emitted with a trailing `?`. Walking right-to-left,
+ * a param is emitted-optional iff it is itself omittable (`isOptional || isNilable`)
+ * and every later non-vararg param is too — a required param blocks every param to
+ * its left, since TS forbids a required parameter after an optional one. A trailing
+ * vararg (rendered `...args`, never `?`) does not break the preceding run. Exported so
+ * the api-doc lowering keys `is_optional` off the identical rule, keeping the rendered
+ * `/api` signature byte-consistent with the `.d.ts`.
+ */
+export function paramOptionalFlags(params: readonly LibraryParam[]): boolean[] {
+  const flags = new Array<boolean>(params.length).fill(false);
+  let laterAllOptional = true;
+  for (let i = params.length - 1; i >= 0; i--) {
+    const param = params[i] as LibraryParam;
+    if (param.isVararg) continue;
+    const selfOptional = param.isOptional || param.isNilable === true;
+    if (laterAllOptional && selfOptional) {
+      flags[i] = true;
+    } else {
+      laterAllOptional = false;
+    }
+  }
+  return flags;
+}
+
 function renderParams(params: readonly LibraryParam[], ctx: MapContext): string {
+  const optionalFlags = paramOptionalFlags(params);
   return params
     .map((param, index) => {
       const mapped = mapTypes(param.types, ctx);
       if (param.isVararg) {
         return `...args: ${varargElementType(mapped)}`;
       }
-      const optional = param.isOptional ? "?" : "";
+      const optional = optionalFlags[index] ? "?" : "";
       return `${safeParamName(param.name, index)}${optional}: ${mapped}`;
     })
     .join(", ");
@@ -129,16 +229,22 @@ function renderParams(params: readonly LibraryParam[], ctx: MapContext): string
 function renderReturn(returns: readonly LibraryParam[], ctx: MapContext): string {
   if (returns.length === 0) return "void";
   if (returns.length === 1) return mapTypes((returns[0] as LibraryParam).types, ctx);
-  return luaMultiReturn(returns.map((ret) => mapTypes(ret.types, ctx)));
+  const last = returns[returns.length - 1] as LibraryParam;
+  const restTail = last.types.length === 1 && last.types[0] === LUALS_VARARG_TOKEN;
+  return luaMultiReturn(
+    returns.map((ret) => mapTypes(ret.types, ctx)),
+    restTail,
+  );
 }
 
-function pushDoc(lines: string[], summary: string, indent: string): void {
-  for (const line of renderDocComment({ summary })) lines.push(`${indent}${line}`);
+function pushDoc(lines: string[], summary: string, indent: string, deprecated?: string): void {
+  const parts = deprecated !== undefined ? { summary, deprecated } : { summary };
+  for (const line of renderDocComment(parts)) lines.push(`${indent}${line}`);
 }
 
 function renderAlias(alias: LibraryAlias, ctx: MapContext): string[] {
   const lines: string[] = [];
-  pushDoc(lines, alias.doc, INDENT);
+  pushDoc(lines, alias.doc, INDENT, alias.deprecated);
   lines.push(`${INDENT}type ${sanitizeTypeName(alias.name)} = ${mapTypes(alias.types, ctx)};`);
   return lines;
 }
@@ -147,15 +253,17 @@ function renderInterface(
   iface: LibraryInterface,
   ctx: MapContext,
   interfaceNames: ReadonlySet<string>,
+  externalTokens: ReadonlySet<string>,
 ): string[] {
   const lines: string[] = [];
-  pushDoc(lines, iface.brief, INDENT);
+  pushDoc(lines, iface.brief, INDENT, iface.deprecated);
   const ifaceCtx = scopeGenerics(ctx, iface.generics);
   const params = renderGenericParams(iface.generics, ifaceCtx);
-  const extendsClause = renderExtends(iface, ifaceCtx, interfaceNames);
+  const extendsClause = renderExtends(iface, ifaceCtx, interfaceNames, externalTokens);
   lines.push(`${INDENT}interface ${sanitizeTypeName(iface.name)}${params}${extendsClause} {`);
   const body = INDENT + INDENT;
   for (const field of iface.fields) {
+    if (!isPublicField(field)) continue;
     // A base's self-receiving lifecycle hook is emitted as a permissive optional
     // method (`name?(...args: any[]): ret`) so a concrete subinterface's refined
     // override stays assignable under `extends`; strict function-field variance
@@ -172,7 +280,8 @@ function renderInterface(
     lines.push(`${body}${memberKey(field.name)}${optional}: ${mapTypes(field.types, ifaceCtx)};`);
   }
   for (const method of iface.methods) {
-    pushDoc(lines, method.brief, body);
+    if (!isPublicMethod(method)) continue;
+    pushDoc(lines, method.brief, body, method.deprecated);
     const methodCtx = scopeGenerics(ifaceCtx, method.generics);
     const methodParams = renderGenericParams(method.generics, methodCtx);
     lines.push(
@@ -182,13 +291,39 @@ function renderInterface(
       )}): ${renderReturn(method.returns, methodCtx)};`,
     );
   }
+  // A class `@overload fun(...)` becomes an interface call signature, making the
+  // instance callable (`event(...)`, `promise(...)`) the way the metatable's `__call`
+  // does at runtime. Rendered after the members with its own doc comment.
+  for (const overload of iface.overloads ?? []) {
+    pushDoc(lines, overload.doc, body);
+    lines.push(`${body}${mapLualsCallSignature(overload.type, ifaceCtx).ts};`);
+  }
   lines.push(`${INDENT}}`);
   return lines;
 }
 
+/**
+ * The module object's public fields rendered as module-level `export const`s — the
+ * constants a returned module table (`return Squid`) carries. Emitted in place of the
+ * standalone interface, since consumers reach them as `squid.TRACE`, not `Squid.TRACE`.
+ */
+function renderModuleConstants(iface: LibraryInterface, ctx: MapContext): string[] {
+  const lines: string[] = [];
+  for (const field of iface.fields) {
+    if (!isPublicField(field)) continue;
+    pushDoc(lines, field.doc, INDENT);
+    const name =
+      TS_IDENTIFIER.test(field.name) && !TS_RESERVED_NAMES.has(field.name)
+        ? field.name
+        : sanitizeTypeName(field.name);
+    lines.push(`${INDENT}export const ${name}: ${mapTypes(field.types, ctx)};`);
+  }
+  return lines;
+}
+
 function renderModuleFunction(fn: LibraryMethod, ctx: MapContext): string[] {
   const lines: string[] = [];
-  pushDoc(lines, fn.brief, INDENT);
+  pushDoc(lines, fn.brief, INDENT, fn.deprecated);
   const fnCtx = scopeGenerics(ctx, fn.generics);
   const genericParams = renderGenericParams(fn.generics, fnCtx);
   const params = renderParams(fn.params, fnCtx);
@@ -220,6 +355,7 @@ function renderModuleFunction(fn: LibraryMethod, ctx: MapContext): string[] {
 export function buildModelContext(
   model: LibraryModel,
   typeRenames?: Record<string, string>,
+  externalTypes?: Record<string, ExternalTypeRef>,
 ): MapContext {
   const declaredNames = [
     ...model.interfaces.map((iface) => iface.name),
@@ -227,9 +363,18 @@ export function buildModelContext(
   ];
   const nameRenames: Record<string, string> = {};
   for (const name of declaredNames) nameRenames[name] = sanitizeTypeName(name);
+  const externalRenames = externalTypeRenames(externalTypes);
+  for (const [token, alias] of Object.entries(externalRenames)) {
+    const collision = declaredNames.find((name) => sanitizeTypeName(name) === alias);
+    if (collision !== undefined) {
+      throw new Error(
+        `buildModelContext: external type "${token}" resolves to local name "${alias}", which the model already declares as "${collision}".`,
+      );
+    }
+  }
   return {
-    knownNames: new Set(declaredNames),
-    typeRenames: { ...(typeRenames ?? {}), ...nameRenames },
+    knownNames: new Set([...declaredNames, ...Object.values(externalRenames)]),
+    typeRenames: { ...(typeRenames ?? {}), ...externalRenames, ...nameRenames },
   };
 }
 
@@ -240,13 +385,26 @@ export function buildModelContext(
  * `unknown` inside `mapLualsType` exactly as the fidelity report records them.
  */
 export function emitLibraryDeclarations(model: LibraryModel, opts: EmitLibraryOptions): string {
-  const ctx = buildModelContext(model, opts.typeRenames);
+  const ctx = buildModelContext(model, opts.typeRenames, opts.externalTypes);
 
   const interfaceNames = new Set(model.interfaces.map((iface) => iface.name));
+  const externalTokens = new Set(Object.keys(opts.externalTypes ?? {}));
   const out: string[] = ["/** @noResolution */", `declare module '${opts.moduleId}' {`];
+  out.push(...renderExternalImports(opts.externalTypes));
   for (const alias of model.aliases) out.push(...renderAlias(alias, ctx));
-  for (const iface of model.interfaces) out.push(...renderInterface(iface, ctx, interfaceNames));
-  for (const fn of model.moduleFunctions) out.push(...renderModuleFunction(fn, ctx));
+  for (const iface of model.interfaces) {
+    // The module object's fields become module-level `export const`s (below), so it is
+    // not also rendered as a standalone interface.
+    if (iface.name === model.moduleObject) {
+      out.push(...renderModuleConstants(iface, ctx));
+      continue;
+    }
+    out.push(...renderInterface(iface, ctx, interfaceNames, externalTokens));
+  }
+  for (const fn of model.moduleFunctions) {
+    if (!isPublicMethod(fn)) continue;
+    out.push(...renderModuleFunction(fn, ctx));
+  }
   out.push("}");
   return `${out.join("\n")}\n`;
 }