@defold-typescript/types 0.40.0 → 0.42.0

package/scripts/shared-handle-methods.ts

@@ -0,0 +1,53 @@
+import type { ModuleManifestEntry } from "./regen";
+
+// A method the engine shares across several handle classes where a release's
+// ref-doc documents it on only some of them. The handles it omits are restored
+// from the documented one, so a doc omission never drops a method the engine
+// still binds. Applies only where the source handle documents it.
+export interface SharedHandleMethod {
+  readonly namespace: string;
+  readonly method: string;
+  readonly source: string;
+  readonly handles: readonly string[];
+  readonly evidence: string;
+}
+
+const TCP_ANY =
+  'LuaSocket tcp.c binds it in the one method table every tcp class shares, and checks its argument with auxiliar_checkgroup(L, "tcp{any}", 1)';
+
+export const SHARED_HANDLE_METHODS: readonly SharedHandleMethod[] = (
+  ["getstats", "setstats"] as const
+).map((method) => ({
+  namespace: "socket",
+  method,
+  source: "client",
+  handles: ["master", "server"],
+  evidence: TCP_ANY,
+}));
+
+interface DocElement {
+  readonly name: string;
+}
+
+export function restoreSharedHandleMethods(
+  modules: readonly ModuleManifestEntry[],
+): ModuleManifestEntry[] {
+  return modules.map((entry) => {
+    const shared = SHARED_HANDLE_METHODS.filter((row) => row.namespace === entry.namespace);
+    if (shared.length === 0) return entry;
+    const doc = entry.doc as { elements: DocElement[] };
+    const declared = new Set(doc.elements.map((element) => element.name));
+    const restored: DocElement[] = [];
+    for (const { method, source, handles } of shared) {
+      const documented = doc.elements.find((element) => element.name === `${source}:${method}`);
+      if (documented === undefined) continue;
+      for (const handle of handles) {
+        const name = `${handle}:${method}`;
+        if (!declared.has(name)) restored.push({ ...documented, name });
+      }
+    }
+    return restored.length === 0
+      ? entry
+      : { ...entry, doc: { ...doc, elements: [...doc.elements, ...restored] } };
+  });
+}

package/scripts/signature-store-fs.ts

@@ -25,6 +25,7 @@ export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures"
 export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
 export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
 export const RENDER_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "render.json");
+export const SYS_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "sys.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/scripts/sync-api-docs.ts

@@ -1,6 +1,6 @@
-import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
 import { DEFOLD_TYPE_MAP } from "../src/core-types";
 import { parseScriptApi } from "../src/script-api";
@@ -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.1";
+export const DEFOLD_VERSION = "1.13.2";
 export const refDocUrl = (version = DEFOLD_VERSION): string =>
   `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
 
@@ -52,13 +52,24 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
     "doc/scripts-box2d-v3-script_box2d_world_v3.cpp_doc.json",
   ]),
   entry("buffer", "doc/scripts-script_buffer.cpp_doc.json"),
+  entry("bullet3d", "doc/scripts-bullet3d-script_bullet3d.cpp_doc.json"),
+  entry(
+    "bullet3d.collision_object",
+    "doc/scripts-bullet3d-script_bullet3d_collision_object.cpp_doc.json",
+  ),
+  entry("bullet3d.constraint", "doc/scripts-bullet3d-script_bullet3d_constraint.cpp_doc.json"),
+  entry("bullet3d.rigid_body", "doc/scripts-bullet3d-script_bullet3d_rigid_body.cpp_doc.json"),
+  entry("bullet3d.shape", "doc/scripts-bullet3d-script_bullet3d_shape.cpp_doc.json"),
+  entry("bullet3d.world", "doc/scripts-bullet3d-script_bullet3d_world.cpp_doc.json"),
   // Camera and component namespaces merge their DDF messages/properties into
   // the callable script API so release snapshots retain every declared symbol.
   entry("camera", "doc/gamesys-camera_ddf.proto_doc.json", undefined, [
     "doc/render-render_script_camera.cpp_doc.json",
   ]),
   entry("collectionfactory", "doc/scripts-script_collection_factory.cpp_doc.json"),
-  entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json"),
+  entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json", undefined, [
+    "doc/gamesys-collectionproxy_ddf.proto_doc.json",
+  ]),
   entry("compute", "doc/scripts-script_compute.cpp_doc.json"),
   entry("crash", "doc/script_crash.cpp_doc.json"),
   entry("factory", "doc/scripts-script_factory.cpp_doc.json"),
@@ -115,11 +126,11 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
 export const UNMAPPED: ReadonlyMap<string, string> = new Map();
 
 // A Lua script namespace is a lowercase, dot-separated identifier (`sys`,
-// `b2d.body`). The native C/C++ SDK docs (`dmGraphics`, …), the C# bindings
+// `b2d.body`, `bullet3d.rigid_body`). The native C/C++ SDK docs (`dmGraphics`, …), the C# bindings
 // (`cs-*`), and the struct-only docs (empty `info.namespace`) fail this shape,
 // so the upstream-coverage guard skips them structurally rather than listing
 // each by hand — that keeps the guard self-maintaining as the SDK grows.
-const LUA_NAMESPACE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
+const LUA_NAMESPACE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 
 // Lowercase-identifier namespaces that pass LUA_NAMESPACE but are intentionally
 // not wired through SYNC_MANIFEST, each with a sourced reason (mirrors the
@@ -205,7 +216,7 @@ function editorVm(namespace: string): SyncManifestEntry {
 function entry(
   namespace: string,
   zipEntry: string,
-  fixture: string = `fixtures/defold-1.13.1/${namespace.replace(/\./g, "_")}_doc.json`,
+  fixture: string = `fixtures/defold-1.13.2/${namespace.replace(/\./g, "_")}_doc.json`,
   mergeEntries?: readonly string[],
 ): SyncManifestEntry {
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };
@@ -393,6 +404,21 @@ export function extractFixtures(
   });
 }
 
+// Since 1.13.2 the ref-doc zip ships LuaLS annotation files beside the JSON:
+// `doc/<namespace>.lua` for the game runtime and `doc/<namespace>.editor_script`
+// for the editor VM. They are vendored verbatim, never parsed at sync time.
+const ANNOTATION_ENTRY = /^doc\/([^/]+\.(?:lua|editor_script))$/;
+
+export function extractAnnotationFixtures(zip: ZipAccessor): ExtractedFixture[] {
+  const out: ExtractedFixture[] = [];
+  for (const zipEntry of [...zip.entries()].sort()) {
+    const file = ANNOTATION_ENTRY.exec(zipEntry)?.[1];
+    if (file === undefined) continue;
+    out.push({ namespace: file, fixture: `annotations/${file}`, contents: zip.read(zipEntry) });
+  }
+  return out;
+}
+
 export type FixtureSyncStatus = "clean" | "drift" | "created";
 
 export interface FixtureSyncResult {
@@ -431,7 +457,8 @@ export function syncFixtures(zip: ZipAccessor, options: SyncOptions = {}): Fixtu
 
 // Compare/write a set of already-extracted fixtures against disk. Shared by
 // the core (zip) and extension (`.script_api`) sync paths so both honor the
-// identical created/clean/drift + format-on-write semantics.
+// identical created/clean/drift + format-on-write semantics. A non-JSON fixture
+// (a vendored annotation file) compares and writes byte-for-byte.
 export function syncExtractedFixtures(
   items: readonly ExtractedFixture[],
   options: Omit<SyncOptions, "manifest"> = {},
@@ -442,15 +469,21 @@ export function syncExtractedFixtures(
   const results: FixtureSyncResult[] = [];
   for (const item of items) {
     const path = resolve(root, item.fixture);
+    const json = item.fixture.endsWith(".json");
     const existing = readFixtureOrNull(path);
     const status: FixtureSyncStatus =
       existing === null
         ? "created"
-        : canonicalJson(existing) === canonicalJson(item.contents)
+        : (
+              json
+                ? canonicalJson(existing) === canonicalJson(item.contents)
+                : existing === item.contents
+            )
           ? "clean"
           : "drift";
     if (!check && status !== "clean") {
-      writeFileSync(path, format(item.contents));
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, json ? format(item.contents) : item.contents);
     }
     results.push({ namespace: item.namespace, fixture: item.fixture, status });
   }
@@ -630,11 +663,16 @@ if (import.meta.main) {
   const luaStdlibFixtures = extractFixtures(zip, LUA_STDLIB_MANIFEST);
   const editorFixtures = extractFixtures(zip, EDITOR_MANIFEST);
   const editorVmFixtures = extractFixtures(zip, EDITOR_VM_MANIFEST);
+  const annotationFixtures = extractAnnotationFixtures(zip);
   const results = [
     ...syncExtractedFixtures(coreFixtures, { check }),
     ...syncExtractedFixtures(luaStdlibFixtures, { check }),
     ...syncExtractedFixtures(editorFixtures, { check }),
     ...syncExtractedFixtures(editorVmFixtures, { check }),
+    ...syncExtractedFixtures(annotationFixtures, {
+      check,
+      fixturesRoot: resolve(PACKAGE_ROOT, `fixtures/defold-${DEFOLD_VERSION}`),
+    }),
   ];
   const syncedDocs = coreFixtures.map((f) => ({
     namespace: f.namespace,

package/src/api-doc.ts

@@ -1,3 +1,5 @@
+import { correctedDoc, docCorrectionKey } from "./doc-corrections";
+
 export interface ApiModule {
   namespace: string;
   brief: string;
@@ -7,6 +9,39 @@ export interface ApiModule {
   constants: ApiConstant[];
   properties: ApiProperty[];
   typedefs: ApiTypedef[];
+  /**
+   * Each ref-doc `ENUM`, whose members are also lowered into `constants`. Absent
+   * on a hand-built module, which reads the same as an empty list.
+   */
+  enums?: ApiEnum[];
+  /** Each ref-doc `STRUCT`. Absent on a hand-built module, read as an empty list. */
+  structs?: ApiStruct[];
+}
+
+/** A ref-doc `STRUCT`: a named table shape. */
+export interface ApiStruct {
+  name: string;
+  brief: string;
+  description: string;
+  members: ApiStructMember[];
+}
+
+/** One `STRUCT` member; upstream marks an optional one with a `name?` suffix. */
+export interface ApiStructMember {
+  name: string;
+  doc: string;
+  /** One LuaLS type expression. */
+  type: string;
+  isOptional: boolean;
+}
+
+/** A ref-doc `ENUM`: a named set of constants, each lowered into `constants`. */
+export interface ApiEnum {
+  name: string;
+  brief: string;
+  description: string;
+  /** The member FQNs, in documentation order. */
+  members: string[];
 }
 
 export interface ApiProperty {
@@ -24,6 +59,11 @@ export interface ApiTypedef {
   types?: string[];
   /** The type text of each parent an interface-backed typedef extends. */
   extends?: string[];
+  /**
+   * The type an engine ref-doc `TYPEDEF` aliases (`parameters[0].types`): a
+   * handle's `userdata`/`number`, or the arms of a union, literal or record alias.
+   */
+  aliasOf?: string[];
   /** See {@link ApiFunction.global}. */
   global?: true;
 }
@@ -32,6 +72,16 @@ export interface ApiConstant {
   name: string;
   brief: string;
   description: string;
+  /**
+   * Present when the constant is a member of an `ENUM` whose value type is
+   * `string` (`parameters[0].types`); absence means a number, as every
+   * pre-`ENUM` constant is.
+   */
+  valueType?: "string";
+  /** Present when an `ENUM` member is typed `<ENUM>|nil`: some platforms leave it unset. */
+  nilable?: true;
+  /** The documented constant a back-filled one shares its value, and so its type, with. */
+  aliasOf?: string;
   /** See {@link ApiFunction.global}. */
   global?: true;
 }
@@ -122,6 +172,27 @@ function docSourceKey(element: Record<string, unknown>): { docSource?: "upstream
   return element.docSource === "upstream" ? { docSource: "upstream" } : {};
 }
 
+// A function the ref-doc names differently from the name its engine binding
+// registers, so the documented call raises "attempt to call a nil value". Keyed
+// by the ref-doc FQN; `name` is the registered FQN and `evidence` the
+// registration. The parse renames the element, so the declaration, the signature
+// store, the example translations and every audit read the bound name. An entry
+// is deleted once no retained target documents the old name.
+export interface FunctionNameCorrection {
+  readonly name: string;
+  readonly evidence: string;
+}
+
+export const FUNCTION_NAME_CORRECTIONS: ReadonlyMap<string, FunctionNameCorrection> = new Map([
+  [
+    "sys.set_render_enable",
+    {
+      name: "sys.set_render_enabled",
+      evidence: 'script_engine.cpp registers {"set_render_enabled", EngineSys_SetRenderEnabled}',
+    },
+  ],
+]);
+
 export function parseDefoldApiDoc(input: unknown): ApiModule {
   if (!isRecord(input)) {
     throw new Error(`parseDefoldApiDoc: expected object, got ${describeKind(input)}`);
@@ -145,24 +216,99 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
   const constants: ApiConstant[] = [];
   const properties: ApiProperty[] = [];
   const typedefs: ApiTypedef[] = [];
+  const enums: ApiEnum[] = [];
+  const structs: ApiStruct[] = [];
 
   for (const element of elements) {
     if (!isRecord(element)) continue;
     const type = element.type;
     if (type === "FUNCTION") {
-      functions.push(parseFunction(element));
+      const fn = withDocCorrections(parseFunction(element));
+      const corrected = FUNCTION_NAME_CORRECTIONS.get(fn.name);
+      functions.push(corrected === undefined ? fn : { ...fn, name: corrected.name });
     } else if (type === "VARIABLE") {
       variables.push(parseVariable(element));
     } else if (type === "CONSTANT") {
       constants.push(parseConstant(element));
     } else if (type === "PROPERTY") {
-      properties.push(parseProperty(element));
+      const property = parseProperty(element);
+      const doc = correctedDoc(
+        docCorrectionKey(namespace, "property", property.name),
+        property.description,
+      );
+      properties.push(doc === property.description ? property : { ...property, description: doc });
     } else if (type === "TYPEDEF") {
       typedefs.push(parseTypedef(element));
+    } else if (type === "ENUM") {
+      const members = parseEnumMembers(element);
+      constants.push(...members);
+      enums.push({
+        name: stringOr(element.name, ""),
+        brief: stringOr(element.brief, ""),
+        description: stringOr(element.description, ""),
+        members: members.map((m) => m.name),
+      });
+    } else if (type === "STRUCT") {
+      structs.push(parseStruct(element));
+    }
+  }
+
+  return {
+    namespace,
+    brief,
+    description,
+    functions,
+    variables,
+    constants,
+    properties,
+    typedefs,
+    enums,
+    structs,
+  };
+}
+
+// Withholds one overload of a documented function — the one whose `param` has
+// exactly the upstream type `type` — while its same-named siblings still emit.
+// `name` is the local name, like a `skipFunctions` rule.
+export interface SkipOverloadRule {
+  readonly name: string;
+  readonly param: string;
+  readonly type: string;
+}
+
+export function withholdOverloads(
+  module: ApiModule,
+  rules: readonly SkipOverloadRule[],
+): ApiModule {
+  let functions = module.functions;
+  for (const rule of rules) {
+    const fqn = `${module.namespace}.${rule.name}`;
+    const kept = functions.filter(
+      (fn) =>
+        fn.name !== fqn ||
+        !fn.parameters.some(
+          (p) => p.name === rule.param && p.types.length === 1 && p.types[0] === rule.type,
+        ),
+    );
+    if (kept.length === functions.length) {
+      throw new Error(`skipOverloads: ${fqn} has no overload whose ${rule.param} is ${rule.type}`);
     }
+    functions = kept;
   }
+  return functions === module.functions ? module : { ...module, functions };
+}
 
-  return { namespace, brief, description, functions, variables, constants, properties, typedefs };
+// Keyed by the ref-doc FQN, before any `FUNCTION_NAME_CORRECTIONS` rename.
+function withDocCorrections(fn: ApiFunction): ApiFunction {
+  const correct = (slot: "param" | "return") => (p: ApiParameter) => {
+    const doc = correctedDoc(docCorrectionKey(fn.name, slot, p.name), p.doc);
+    return doc === p.doc ? p : { ...p, doc };
+  };
+  return {
+    ...fn,
+    parameters: fn.parameters.map(correct("param")),
+    returnValues: fn.returnValues.map(correct("return")),
+  };
 }
 
 function parseTypedef(element: Record<string, unknown>): ApiTypedef {
@@ -170,16 +316,41 @@ function parseTypedef(element: Record<string, unknown>): ApiTypedef {
   const properties = parseVariableList(element.properties);
   const types = parseStringArray(element.types);
   const parents = parseStringArray(element.extends);
+  const [aliased] = parseParameterList(element.parameters);
+  const aliasOf = aliased?.types ?? [];
   return {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
     ...(types.length > 0 ? { types } : {}),
     ...(parents.length > 0 ? { extends: parents } : {}),
+    ...(aliasOf.length > 0 ? { aliasOf } : {}),
     ...globalKey(element),
   };
 }
 
+function parseStruct(element: Record<string, unknown>): ApiStruct {
+  const raw = Array.isArray(element.members) ? element.members : [];
+  const members: ApiStructMember[] = [];
+  for (const member of raw) {
+    if (!isRecord(member)) continue;
+    const name = stringOr(member.name, "");
+    const isOptional = name.endsWith("?");
+    members.push({
+      name: isOptional ? name.slice(0, -1) : name,
+      doc: stringOr(member.doc, ""),
+      type: stringOr(member.type, ""),
+      isOptional,
+    });
+  }
+  return {
+    name: stringOr(element.name, ""),
+    brief: stringOr(element.brief, ""),
+    description: stringOr(element.description, ""),
+    members,
+  };
+}
+
 function parseProperty(element: Record<string, unknown>): ApiProperty {
   const brief = stringOr(element.brief, "");
   const span = /<span class="type">([^<]+)<\/span>/.exec(brief);
@@ -207,6 +378,33 @@ function parseConstant(element: Record<string, unknown>): ApiConstant {
   };
 }
 
+// A member carries one `doc` string where a constant carried `brief` and
+// `description`; both take it.
+function parseEnumMembers(element: Record<string, unknown>): ApiConstant[] {
+  // A member named bare (1.13.2's bullet3d enums) is registered on the enum's
+  // own namespace, so it takes that prefix.
+  const enumName = stringOr(element.name, "");
+  const owner = enumName.includes(".") ? enumName.slice(0, enumName.lastIndexOf(".")) : "";
+  const qualify = (name: string): string =>
+    name.includes(".") || owner === "" ? name : `${owner}.${name}`;
+  const [value] = parseParameterList(element.parameters);
+  const valueType = value?.types.length === 1 && value.types[0] === "string" ? "string" : null;
+  const raw = Array.isArray(element.members) ? element.members : [];
+  const out: ApiConstant[] = [];
+  for (const member of raw) {
+    if (!isRecord(member)) continue;
+    const doc = stringOr(member.doc, "");
+    out.push({
+      name: qualify(stringOr(member.name, "")),
+      brief: doc,
+      description: doc,
+      ...(valueType === null ? {} : { valueType }),
+      ...(stringOr(member.type, "").endsWith("|nil") ? { nilable: true } : {}),
+    });
+  }
+  return out;
+}
+
 function parseFunction(element: Record<string, unknown>): ApiFunction {
   return {
     name: stringOr(element.name, ""),