@defold-typescript/library-types 0.22.0 → 0.23.0

package/scripts/apply-luals-overrides.ts

@@ -0,0 +1,63 @@
+/**
+ * Per-target corrections applied to a parsed `LibraryModel` after the merge, for the
+ * cases where upstream LuaLS annotations diverge from the library's runtime and the
+ * fixtures freeze the annotation verbatim (so it is not hand-patchable in the fixture
+ * or the emitted `.d.ts`). The two shapes covered are a module function whose trailing
+ * parameter is runtime-optional despite a non-`|nil` `@param`, and an interface method
+ * whose `@return` omits an alternative arm. Every named target must exist — a missing
+ * function, param, interface, or method throws naming the absent key, mirroring
+ * `buildTargetModel`'s loud-fail on an absent `ownFile`, so a stale override never
+ * degrades into a silent no-op.
+ */
+
+import type { LibraryModel } from "./parse-luals";
+
+export interface AnnotationOverrides {
+  moduleFunctions?: Record<string, { params?: Record<string, { optional?: boolean }> }>;
+  interfaces?: Record<string, { methods?: Record<string, { return?: string }> }>;
+}
+
+export function applyAnnotationOverrides(
+  model: LibraryModel,
+  overrides: AnnotationOverrides,
+): LibraryModel {
+  for (const [fnName, fnOverride] of Object.entries(overrides.moduleFunctions ?? {})) {
+    const fn = model.moduleFunctions.find((f) => f.name === fnName);
+    if (!fn) {
+      throw new Error(
+        `applyAnnotationOverrides: module function "${fnName}" is absent from the model.`,
+      );
+    }
+    for (const [paramName, paramOverride] of Object.entries(fnOverride.params ?? {})) {
+      const param = fn.params.find((p) => p.name === paramName);
+      if (!param) {
+        throw new Error(
+          `applyAnnotationOverrides: param "${paramName}" of module function "${fnName}" is absent from the model.`,
+        );
+      }
+      if (paramOverride.optional) param.isOptional = true;
+    }
+  }
+  for (const [ifaceName, ifaceOverride] of Object.entries(overrides.interfaces ?? {})) {
+    const iface = model.interfaces.find((i) => i.name === ifaceName);
+    if (!iface) {
+      throw new Error(
+        `applyAnnotationOverrides: interface "${ifaceName}" is absent from the model.`,
+      );
+    }
+    for (const [methodName, methodOverride] of Object.entries(ifaceOverride.methods ?? {})) {
+      const method = iface.methods.find((m) => m.name === methodName);
+      if (!method) {
+        throw new Error(
+          `applyAnnotationOverrides: method "${methodName}" of interface "${ifaceName}" is absent from the model.`,
+        );
+      }
+      if (methodOverride.return !== undefined) {
+        method.returns = [
+          { name: "", types: [methodOverride.return], doc: "", isOptional: false, isVararg: false },
+        ];
+      }
+    }
+  }
+  return model;
+}

package/scripts/emit-library-dts.ts

@@ -27,12 +27,14 @@ import {
 } from "@defold-typescript/types";
 import {
   type MapContext,
+  mapLualsCallSignature,
   mapLualsType,
   matchSelfHookField,
   scopeGenerics,
 } from "./map-luals-types";
 import type {
   LibraryAlias,
+  LibraryField,
   LibraryGeneric,
   LibraryInterface,
   LibraryMethod,
@@ -47,6 +49,20 @@ export interface EmitLibraryOptions {
 
 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, "_");
@@ -113,14 +129,40 @@ function renderExtends(
   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(", ");
@@ -156,6 +198,7 @@ function renderInterface(
   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,6 +215,7 @@ function renderInterface(
     lines.push(`${body}${memberKey(field.name)}${optional}: ${mapTypes(field.types, ifaceCtx)};`);
   }
   for (const method of iface.methods) {
+    if (!isPublicMethod(method)) continue;
     pushDoc(lines, method.brief, body);
     const methodCtx = scopeGenerics(ifaceCtx, method.generics);
     const methodParams = renderGenericParams(method.generics, methodCtx);
@@ -182,10 +226,36 @@ 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);
@@ -245,8 +315,19 @@ export function emitLibraryDeclarations(model: LibraryModel, opts: EmitLibraryOp
   const interfaceNames = new Set(model.interfaces.map((iface) => iface.name));
   const out: string[] = ["/** @noResolution */", `declare module '${opts.moduleId}' {`];
   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));
+  }
+  for (const fn of model.moduleFunctions) {
+    if (!isPublicMethod(fn)) continue;
+    out.push(...renderModuleFunction(fn, ctx));
+  }
   out.push("}");
   return `${out.join("\n")}\n`;
 }

package/scripts/lower-api-doc.ts

@@ -15,34 +15,36 @@
 
 import {
   buildModelContext,
+  isPublicField,
+  isPublicMethod,
   mapTypes,
+  paramOptionalFlags,
   renderGenericParams,
   sanitizeTypeName,
 } from "./emit-library-dts";
 import { type MapContext, scopeGenerics } from "./map-luals-types";
 import type { LibraryField, LibraryMethod, LibraryModel, LibraryParam } from "./parse-luals";
 
-// A field with an explicit non-public visibility is internal surface; keep only
-// fields with no visibility or an explicit `public`, mirroring how LuaLS hides
-// `private`/`protected`/`package` members from a class's public shape.
-function isPublicField(field: LibraryField): boolean {
-  return field.visibility === undefined || field.visibility === "public";
-}
-
 // Each type token is mapped independently (one mapped TS string per token) so the
 // ref-doc `types` array stays token-per-slot the way engine ref-docs are shaped.
 function mapTokens(tokens: readonly string[], ctx: MapContext): string[] {
   return tokens.map((token) => mapTypes([token], ctx));
 }
 
-function parameterElement(param: LibraryParam, ctx: MapContext): Record<string, unknown> {
+function parameterElement(
+  param: LibraryParam,
+  isOptional: boolean,
+  ctx: MapContext,
+): Record<string, unknown> {
   // A vararg's element type stays a plain mapped token here; the renderer arrayifies
   // it (`...args: T[]`) from the `is_vararg` flag, keeping the JSON structurally honest.
+  // `isOptional` comes from the emitter's trailing-run rule (paramOptionalFlags), not
+  // `param.isOptional` alone, so the `/api` signature matches the emitted `.d.ts`.
   return {
     name: param.isVararg ? "...args" : param.name,
     doc: param.doc,
     types: mapTokens(param.types, ctx),
-    is_optional: param.isOptional ? "True" : "False",
+    is_optional: isOptional ? "True" : "False",
     is_vararg: param.isVararg ? "True" : "False",
   };
 }
@@ -54,13 +56,16 @@ function returnElement(ret: LibraryParam, ctx: MapContext): Record<string, unkno
 function functionElement(method: LibraryMethod, ctx: MapContext): Record<string, unknown> {
   const fnCtx = scopeGenerics(ctx, method.generics);
   const generics = renderGenericParams(method.generics, fnCtx);
+  const optionalFlags = paramOptionalFlags(method.params);
   return {
     type: "FUNCTION",
     name: method.name,
     brief: method.brief,
     description: method.brief,
     ...(generics !== "" ? { generics } : {}),
-    parameters: method.params.map((param) => parameterElement(param, fnCtx)),
+    parameters: method.params.map((param, index) =>
+      parameterElement(param, optionalFlags[index] ?? false, fnCtx),
+    ),
     returnvalues: method.returns.map((ret) => returnElement(ret, fnCtx)),
   };
 }
@@ -74,6 +79,18 @@ function propertyElement(field: LibraryField, ctx: MapContext): Record<string, u
   };
 }
 
+// A module object's field lowered as a top-level `VARIABLE` — the ref-doc shape for a
+// module constant (`squid.TRACE`), matching the emitter's module-level `export const`.
+function variableElement(field: LibraryField, ctx: MapContext): Record<string, unknown> {
+  return {
+    type: "VARIABLE",
+    name: field.name,
+    brief: field.doc,
+    description: field.doc,
+    types: mapTokens(field.types, ctx),
+  };
+}
+
 export function lowerLibraryModel(
   model: LibraryModel,
   { namespace, typeRenames }: { namespace: string; typeRenames?: Record<string, string> },
@@ -82,12 +99,24 @@ export function lowerLibraryModel(
   const elements: Record<string, unknown>[] = [];
 
   for (const fn of model.moduleFunctions) {
+    if (!isPublicMethod(fn)) continue;
     elements.push(functionElement(fn, ctx));
   }
 
   for (const iface of model.interfaces) {
     const ifaceCtx = scopeGenerics(ctx, iface.generics);
-    const functions = iface.methods.map((method) => functionElement(method, ifaceCtx));
+    // The module object's public fields are module-level constants, lowered as top-level
+    // VARIABLE elements rather than a TYPEDEF named after the class.
+    if (iface.name === model.moduleObject) {
+      for (const field of iface.fields) {
+        if (!isPublicField(field)) continue;
+        elements.push(variableElement(field, ifaceCtx));
+      }
+      continue;
+    }
+    const functions = iface.methods
+      .filter(isPublicMethod)
+      .map((method) => functionElement(method, ifaceCtx));
     const properties = iface.fields
       .filter(isPublicField)
       .map((field) => propertyElement(field, ifaceCtx));
@@ -103,11 +132,14 @@ export function lowerLibraryModel(
     elements.push({ type: "TYPEDEF", name: sanitizeTypeName(alias.name) });
   }
 
-  // The module's own `@class` (named for the namespace, e.g. `@class druid`)
-  // carries the library's summary; use it as the page description so a
-  // LuaLS-sourced library reads with an intro like every other `/api` page,
-  // rather than opening on a bare provenance block. `brief` is its first line.
-  const moduleClass = model.interfaces.find((iface) => iface.name === namespace);
+  // The module's own `@class` carries the library's summary; use it as the page
+  // description so a LuaLS-sourced library reads with an intro like every other `/api`
+  // page, rather than opening on a bare provenance block. `brief` is its first line.
+  // A tracked `moduleObject` names it directly (squid's `Squid` != namespace `squid`);
+  // otherwise fall back to the class named for the namespace (`@class druid`).
+  const moduleClass = model.interfaces.find(
+    (iface) => iface.name === (model.moduleObject ?? namespace),
+  );
   const description = moduleClass?.brief ?? "";
   const brief = description.split("\n")[0] ?? "";
 

package/scripts/luals-fidelity.ts

@@ -10,6 +10,7 @@
  * sorted-unique token list so the gap is visible instead of silent.
  */
 
+import { isPublicField, isPublicMethod } from "./emit-library-dts";
 import { type MapContext, mapLualsType, scopeGenerics } from "./map-luals-types";
 import type { LibraryGeneric, LibraryModel } from "./parse-luals";
 
@@ -80,12 +81,17 @@ export function buildFidelityReport(
       );
     }
     mapConstraints(iface.generics, ifaceCtx);
+    // A class `@overload fun(...)` is emitted as a call signature, so its type token
+    // counts toward coverage exactly like a field or method type.
+    for (const overload of iface.overloads ?? []) mapTokens([overload.type], ifaceCtx);
     for (const field of iface.fields) {
+      if (!isPublicField(field)) continue;
       totalMembers++;
       if (undocumented(field.doc)) undocumentedMembers++;
       mapTokens(field.types, ifaceCtx);
     }
     for (const method of iface.methods) {
+      if (!isPublicMethod(method)) continue;
       totalMembers++;
       if (undocumented(method.brief)) undocumentedMembers++;
       const methodCtx = scopeGenerics(ifaceCtx, method.generics);
@@ -96,6 +102,7 @@ export function buildFidelityReport(
   }
 
   for (const fn of model.moduleFunctions) {
+    if (!isPublicMethod(fn)) continue;
     totalMembers++;
     if (undocumented(fn.brief)) undocumentedMembers++;
     const fnCtx = scopeGenerics(ctx, fn.generics);

package/scripts/map-luals-types.ts

@@ -126,7 +126,17 @@ function needsArrayParens(tsExpr: string): boolean {
   );
 }
 
-function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string {
+/**
+ * The mapped `(params)` list and `ret` type of a `fun(...)` token, shared by the
+ * arrow-form `mapFunction` and the colon-return `mapLualsCallSignature`. The only
+ * difference between the two consumers is the separator (`=>` vs `:`), so both the
+ * param handling (typed/untyped/vararg) and the single/multi-return logic live here.
+ */
+function functionParts(
+  token: string,
+  ctx: MapContext,
+  unknowns: string[],
+): { paramList: string; ret: string } {
   const open = token.indexOf("(");
   const close = matchBracket(token, open);
   const paramsStr = token.slice(open + 1, close).trim();
@@ -171,6 +181,11 @@ function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string
       ret = `LuaMultiReturn<[${inner}]>`;
     }
   }
+  return { paramList, ret };
+}
+
+function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string {
+  const { paramList, ret } = functionParts(token, ctx, unknowns);
   return `(${paramList}) => ${ret}`;
 }
 
@@ -275,6 +290,24 @@ export function mapLualsType(token: string, ctx: MapContext): MapResult {
   return { ts, unknowns };
 }
 
+/**
+ * Map a `fun(...)` token (a class `@overload`) to a TypeScript **call signature** —
+ * the colon-return form `(params): ret` an interface uses to become callable, not
+ * the `=>` arrow a field/param function type takes. Shares the exact param/return
+ * computation as `mapFunction`, so nested callback params and multi-returns map
+ * identically. Throws on a non-`fun` token; the parser only ever records `fun(...)`
+ * overloads, so this guards a programming error rather than user input.
+ */
+export function mapLualsCallSignature(token: string, ctx: MapContext): MapResult {
+  const trimmed = token.trim();
+  if (!/^fun\s*\(/.test(trimmed)) {
+    throw new Error(`mapLualsCallSignature: expected a "fun(...)" token, got "${token}".`);
+  }
+  const unknowns: string[] = [];
+  const { paramList, ret } = functionParts(trimmed, ctx, unknowns);
+  return { ts: `(${paramList}): ${ret}`, unknowns };
+}
+
 /**
  * When `types` is exactly one `fun(self: <selfTypeName>, ...)` token — optionally
  * unioned with `nil` — whose first parameter is `self` typed as the enclosing