@defold-typescript/types 0.39.0 → 0.41.0

package/src/emit-messages.ts

@@ -85,6 +85,58 @@ export function applyMessageDeprecations(
   return { entries };
 }
 
+// A payload field whose documented type the engine refuses, with the type it
+// takes instead. `upstream` is the documented type the correction replaces:
+// once the catalog stops declaring it the entry throws and is deleted.
+export interface MessageFieldCorrection {
+  readonly origin: string;
+  readonly name: string;
+  readonly field: string;
+  readonly types: readonly string[];
+  readonly upstream: readonly string[];
+  readonly reason: string;
+}
+
+// Demonstrated by the engine probe only: each entry is a payload the running
+// engine rejected when it held the documented type.
+export const MESSAGE_FIELD_CORRECTIONS: readonly MessageFieldCorrection[] = [
+  {
+    origin: "camera",
+    name: "set_camera",
+    field: "orthographic_projection",
+    types: ["number"],
+    upstream: ["boolean"],
+    reason:
+      "the engine decodes the payload into a number field and raises `number expected, got boolean` for the documented boolean",
+  },
+];
+
+export function applyMessageFieldCorrections(
+  catalog: MessageCatalog,
+  overlay: readonly MessageFieldCorrection[] = MESSAGE_FIELD_CORRECTIONS,
+): MessageCatalog {
+  const entries = catalog.entries.map((entry) => ({
+    ...entry,
+    payload: entry.payload.map((field) => ({ ...field })),
+  }));
+  for (const correction of overlay) {
+    const field = entries
+      .find((entry) => entry.origin === correction.origin && entry.name === correction.name)
+      ?.payload.find((candidate) => candidate.name === correction.field);
+    const identity = `(origin=${correction.origin}, name=${correction.name}, field=${correction.field})`;
+    if (field === undefined) {
+      throw new Error(`applyMessageFieldCorrections: no catalog field matches ${identity}`);
+    }
+    if (field.types.join("|") !== correction.upstream.join("|")) {
+      throw new Error(
+        `applyMessageFieldCorrections: upstream now declares ${field.types.join("|")} for ${identity}; delete the correction`,
+      );
+    }
+    field.types = [...correction.types];
+  }
+  return { entries };
+}
+
 const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const ENGINE_TYPES = [
   "Hash",

package/src/engine-globals.d.ts

@@ -12,8 +12,8 @@ declare global {
   function hash<S extends string>(s: S): Core.Hash<S>;
   /** Render a `Hash` handle as its hexadecimal string. */
   function hash_to_hex(h: Core.Hash): string;
-  /** Pretty-print any value to the console for debugging. */
-  function pprint(v: unknown): void;
+  /** Pretty-print any values to the console for debugging. */
+  function pprint(...args: unknown[]): void;
   /**
    * A typed handle to a resource the engine owns — a GUI node, a texture, a
    * render target, a physics body, a socket, and so on. You get one back from an

package/src/example-store.ts

@@ -1,3 +1,7 @@
+import type { ApiModule } from "./api-doc";
+import { htmlToDocText, summaryFor } from "./doc-comment";
+import { fnv1a64 } from "./fnv1a";
+
 // A hand-authored TypeScript translation of one element's ref-doc `@example`,
 // pinned by a hash of the exact source Lua it replaces. A ref-doc re-pin that
 // changes the source Lua flips the hash, so a stale translation stops matching
@@ -5,6 +9,10 @@
 export interface Translation {
   sourceHash: string;
   ts: string;
+  // The authored replacement for the upstream sentence that introduces this
+  // segment. Pinned by the same `sourceHash`, so an upstream rewrite of the
+  // example body drops the caption together with the body.
+  prose?: string;
 }
 
 // An FQN maps to one translation per distinct example body it carries: an
@@ -17,25 +25,20 @@ export interface Translation {
 // replacing the entry silently regresses every demoted surface to raw Lua.
 export type TranslationStore = Record<string, Translation[]>;
 
-const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
-const FNV_PRIME = 0x100000001b3n;
-const U64_MASK = 0xffffffffffffffffn;
+// A prose Lua fence deliberately left as Lua, pinned like a translation by the
+// hash of the fence body, with the reason no TypeScript form fits. Keyed the
+// way `proseLuaFences` keys the fence.
+export type ProseLuaKeepStore = Record<string, { sourceHash: string; reason: string }[]>;
 
-// A pure, dependency-free FNV-1a 64-bit hash over the source's UTF-16 code
-// units, returned as zero-padded hex. Deliberately node- and Bun-free: this
-// module is reachable from `index.ts` (via `emit-dts`), so a `node:crypto` or
-// ambient-`Bun` reference here would fail type-checking in every downstream
-// consumer that compiles the shipped `src/` graph.
+// The `fnv1a64` hash of an example's source, which must stay node- and Bun-free
+// for the reason given there: this module is reachable from `index.ts` (via
+// `emit-dts`).
 //
 // The input is the already-normalized post-`htmlToCodeText` string (per-line
 // trailing whitespace and surrounding blank lines stripped), so the hash is
 // independent of trailing whitespace in the original ref-doc HTML.
 export function hashExampleSource(source: string): string {
-  let hash = FNV_OFFSET_BASIS;
-  for (let i = 0; i < source.length; i++) {
-    hash = ((hash ^ BigInt(source.charCodeAt(i))) * FNV_PRIME) & U64_MASK;
-  }
-  return hash.toString(16).padStart(16, "0");
+  return fnv1a64(source);
 }
 
 // Return the stored TypeScript body only when the FQN exists and one of its
@@ -60,7 +63,7 @@ export function lookupTranslation(
  * emitted as several `@example` blocks only when every one of them has an
  * authored body. A partial resolve would document some of the element's
  * examples and silently drop the rest, so the caller falls back to the
- * whole-blob body instead. An empty hash list is a miss for the same reason —
+ * upstream Lua instead. An empty hash list is a miss for the same reason —
  * it would otherwise report success while documenting nothing.
  */
 export function lookupExampleTranslations(
@@ -77,3 +80,111 @@ export function lookupExampleTranslations(
   }
   return bodies;
 }
+
+/**
+ * The stored body and caption for each of a blob's segments, in the order
+ * given, or `null` the moment one of them does not resolve.
+ *
+ * Same all-or-nothing and empty-list rules as `lookupExampleTranslations`. Each
+ * caption is the entry's authored `prose` when it carries one, else the
+ * segment's upstream prose.
+ */
+export function lookupExampleSegments(
+  store: TranslationStore,
+  fqn: string,
+  segments: readonly { code: string; prose: string }[],
+): { ts: string; prose: string }[] | null {
+  const entries = store[fqn];
+  if (!entries || segments.length === 0) return null;
+  const resolved: { ts: string; prose: string }[] = [];
+  for (const segment of segments) {
+    const sourceHash = hashExampleSource(segment.code);
+    const entry = entries.find((candidate) => candidate.sourceHash === sourceHash);
+    if (!entry) return null;
+    resolved.push({ ts: entry.ts, prose: entry.prose ?? segment.prose });
+  }
+  return resolved;
+}
+
+// A fence `htmlToDocText` opened on a line of its own, located by line index:
+// `open` is the opener, `close` the closing ``` line.
+interface DocFence {
+  open: number;
+  close: number;
+}
+
+// The one reader of prose fences, shared by the enumeration and the swap so the
+// body one hashes is the body the other replaces. Every fence is walked, so a
+// closing ``` of a `text` fence is never read as the opener of the next one.
+function luaDocFences(lines: readonly string[]): DocFence[] {
+  const fences: DocFence[] = [];
+  for (let open = 0; open < lines.length; open += 1) {
+    if (!lines[open]?.startsWith("```")) continue;
+    let close = open + 1;
+    while (close < lines.length && !lines[close]?.startsWith("```")) close += 1;
+    if (close >= lines.length) break;
+    if (lines[open] === "```lua") fences.push({ open, close });
+    open = close;
+  }
+  return fences;
+}
+
+function fenceBody(lines: readonly string[], fence: DocFence): string {
+  return lines.slice(fence.open + 1, fence.close).join("\n");
+}
+
+/**
+ * Swap each ```lua fence in `htmlToDocText` output for the TypeScript pinned
+ * under `key` to its body's hash, leaving every other byte alone. A fence with
+ * no matching entry stays Lua, the same fallback the `@example` ladder keeps.
+ * With `keepSource`, each swapped fence is followed by a blank line and its
+ * untouched body as a ```lua original fence, the pairing the API reference
+ * renders as TypeScript and Lua tabs.
+ */
+export function translateProseFences(
+  markdown: string,
+  key: string,
+  store: TranslationStore,
+  options: { keepSource?: boolean } = {},
+): string {
+  if (!store[key]) return markdown;
+  const lines = markdown.split("\n");
+  const fences = luaDocFences(lines);
+  for (const fence of fences.reverse()) {
+    const lua = fenceBody(lines, fence);
+    const ts = lookupTranslation(store, key, hashExampleSource(lua));
+    if (ts === null) continue;
+    const source = options.keepSource ? ["", "```lua original", ...lua.split("\n"), "```"] : [];
+    lines.splice(
+      fence.open,
+      fence.close - fence.open + 1,
+      "```ts",
+      ...ts.split("\n"),
+      "```",
+      ...source,
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Every ```lua fence in the prose a module documents, keyed the way the emit
+ * and the API reference look its translation up: the namespace description
+ * under the namespace, and a function's summary, parameter and return docs
+ * under the function's name.
+ */
+export function proseLuaFences(module: ApiModule): { key: string; lua: string }[] {
+  const slots: [string, string][] = [
+    [module.namespace, summaryFor(module.brief, module.description)],
+  ];
+  for (const fn of module.functions) {
+    slots.push([fn.name, summaryFor(fn.brief, fn.description)]);
+    for (const slot of [...fn.parameters, ...fn.returnValues]) slots.push([fn.name, slot.doc]);
+  }
+  const out: { key: string; lua: string }[] = [];
+  for (const [key, html] of slots) {
+    const lines = htmlToDocText(html).split("\n");
+    for (const fence of luaDocFences(lines)) out.push({ key, lua: fenceBody(lines, fence) });
+  }
+  return out;
+}

package/src/field-correction-coverage.ts

@@ -0,0 +1,204 @@
+import type { ApiFunction, ApiModule, ApiParameter, ApiStruct } from "./api-doc";
+import {
+  LIST_FIELD_CORRECTIONS,
+  memberCorrectionKey,
+  REQUIRED_FIELD_CORRECTIONS,
+  RETURN_FIELD_OPTIONALITY_CORRECTIONS,
+} from "./emit-dts";
+import { matchBracket, splitTopLevel } from "./luals-type-expr";
+
+// The slot-keyed field corrections are applied to fields recovered from a prose
+// `table` slot. A release that types the slot as a `STRUCT` or an inline record
+// recovers no fields, so each such entry must be stated upstream already or be
+// carried by a member-keyed entry on the struct; anything else would go inert.
+export interface FieldCorrectionTables {
+  readonly required: ReadonlyMap<string, unknown>;
+  readonly list: ReadonlyMap<string, unknown>;
+  readonly optionality: ReadonlyMap<string, unknown>;
+}
+
+export const FIELD_CORRECTION_TABLES: FieldCorrectionTables = {
+  required: REQUIRED_FIELD_CORRECTIONS,
+  list: LIST_FIELD_CORRECTIONS,
+  optionality: RETURN_FIELD_OPTIONALITY_CORRECTIONS,
+};
+
+export interface FieldCorrectionGap {
+  readonly key: string;
+  // The struct whose member would carry the correction, when the path reached one.
+  readonly struct?: string;
+  readonly reason: string;
+}
+
+type Kind = keyof FieldCorrectionTables;
+
+interface Member {
+  readonly name: string;
+  readonly type: string;
+  readonly optional: boolean;
+}
+
+// A slot or member type resolved to the members it declares: a `STRUCT` by name,
+// or an inline `{ name:type, ... }` record.
+interface Shape {
+  readonly struct?: string;
+  readonly members: readonly Member[];
+}
+
+const PROSE_TABLE = "table";
+
+function stripList(type: string): string {
+  let t = type.trim();
+  while (t.endsWith("[]")) t = t.slice(0, -2).trim();
+  while (t.startsWith("(") && matchBracket(t, 0) === t.length - 1) t = t.slice(1, -1).trim();
+  return t;
+}
+
+function recordMembers(record: string): Member[] {
+  return splitTopLevel(record.slice(1, -1), ",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+    .map((part) => {
+      const colon = part.indexOf(":");
+      const raw = colon === -1 ? part : part.slice(0, colon).trim();
+      const optional = raw.endsWith("?");
+      return {
+        name: optional ? raw.slice(0, -1) : raw,
+        type: colon === -1 ? "" : part.slice(colon + 1).trim(),
+        optional,
+      };
+    });
+}
+
+function shapeOf(type: string, structs: ReadonlyMap<string, ApiStruct>): Shape | null {
+  const t = stripList(type);
+  if (t.startsWith("{") && matchBracket(t, 0) === t.length - 1) {
+    return { members: recordMembers(t) };
+  }
+  const struct = structs.get(t);
+  if (struct === undefined) return null;
+  return {
+    struct: struct.name,
+    members: struct.members.map((member) => ({
+      name: member.name,
+      type: member.type,
+      optional: member.isOptional,
+    })),
+  };
+}
+
+function parseKey(key: string): {
+  element: string;
+  kind: "param" | "return";
+  slot: string;
+  segments: string[];
+} | null {
+  const [element, kind, slot, path, ...rest] = key.split(":");
+  if (
+    element === undefined ||
+    slot === undefined ||
+    path === undefined ||
+    rest.length > 0 ||
+    (kind !== "param" && kind !== "return")
+  ) {
+    return null;
+  }
+  return { element, kind, slot, segments: path.split(".").map((s) => s.replace(/\[\]$/, "")) };
+}
+
+function slotsNamed(
+  overloads: readonly ApiFunction[],
+  kind: "param" | "return",
+  slot: string,
+): ApiParameter[] {
+  return overloads.flatMap((fn) =>
+    (kind === "param" ? fn.parameters : fn.returnValues).filter((p) => p.name === slot),
+  );
+}
+
+function slotGap(
+  key: string,
+  table: Kind,
+  slotTypes: readonly string[],
+  segments: readonly string[],
+  structs: ReadonlyMap<string, ApiStruct>,
+  tables: FieldCorrectionTables,
+): FieldCorrectionGap | null {
+  const shapes = slotTypes.map((type) => shapeOf(type, structs)).filter((s) => s !== null);
+  if (shapes.length === 0) {
+    return { key, reason: `slot is typed ${slotTypes.join("|")}, which declares no members` };
+  }
+  for (const initial of shapes) {
+    let shape: Shape = initial;
+    for (const [index, name] of segments.entries()) {
+      const member = shape.members.find((candidate) => candidate.name === name);
+      const struct = shape.struct === undefined ? {} : { struct: shape.struct };
+      if (member === undefined) return { key, ...struct, reason: `no member ${name}` };
+      if (index < segments.length - 1) {
+        const next = shapeOf(member.type, structs);
+        if (next === null) {
+          return { key, ...struct, reason: `member ${name} is typed ${member.type}` };
+        }
+        shape = next;
+        continue;
+      }
+      const carried =
+        shape.struct !== undefined && tables[table].has(memberCorrectionKey(shape.struct, name));
+      const upstream =
+        table === "required" ? !member.optional : table === "optionality" ? member.optional : false;
+      if (!carried && !upstream) {
+        return {
+          key,
+          ...struct,
+          reason: `neither upstream nor a member-keyed ${table} correction states it`,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Every slot-keyed field correction that goes inert on these modules — one
+ * target's, after its skip rules, since a slot in `b2d.fixture` can name a struct
+ * `b2d` declares. An element the target does not declare, and a slot still typed
+ * as a prose `table`, are out of scope and report nothing.
+ */
+export function fieldCorrectionGaps(
+  modules: readonly ApiModule[],
+  tables: FieldCorrectionTables = FIELD_CORRECTION_TABLES,
+): FieldCorrectionGap[] {
+  const structs = new Map(
+    modules.flatMap((module) => module.structs ?? []).map((struct) => [struct.name, struct]),
+  );
+  const functions = modules.flatMap((module) => module.functions);
+  const gaps: FieldCorrectionGap[] = [];
+  for (const table of ["required", "list", "optionality"] as const) {
+    for (const key of tables[table].keys()) {
+      const parsed = parseKey(key);
+      if (parsed === null) continue;
+      const overloads = functions.filter((fn) => fn.name === parsed.element);
+      if (overloads.length === 0) continue;
+      const slots = slotsNamed(overloads, parsed.kind, parsed.slot);
+      if (slots.length === 0) {
+        gaps.push({ key, reason: `${parsed.element} declares no ${parsed.kind} ${parsed.slot}` });
+        continue;
+      }
+      for (const slot of slots) {
+        if (slot.types.includes(PROSE_TABLE)) continue;
+        const gap = slotGap(key, table, slot.types, parsed.segments, structs, tables);
+        if (gap !== null) {
+          gaps.push(gap);
+          break;
+        }
+      }
+    }
+  }
+  return gaps;
+}
+
+export function formatFieldCorrectionGaps(gaps: readonly FieldCorrectionGap[]): string {
+  return gaps
+    .map((gap) => `${gap.key}${gap.struct === undefined ? "" : ` (${gap.struct})`}: ${gap.reason}`)
+    .join("\n");
+}

package/src/fnv1a.ts

@@ -0,0 +1,16 @@
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const U64_MASK = 0xffffffffffffffffn;
+
+// A pure, dependency-free FNV-1a 64-bit hash over the text's UTF-16 code units,
+// returned as zero-padded hex. Deliberately node- and Bun-free: this module is
+// reachable from `index.ts`, so a `node:crypto` or ambient-`Bun` reference here
+// would fail type-checking in every downstream consumer that compiles the
+// shipped `src/` graph.
+export function fnv1a64(text: string): string {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < text.length; i++) {
+    hash = ((hash ^ BigInt(text.charCodeAt(i))) * FNV_PRIME) & U64_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}

package/src/go-overloads.d.ts

@@ -6,12 +6,26 @@ interface ScriptProperty<TValue> {
   readonly __defoldScriptProperty: TValue;
 }
 
+// True when `A` and `B` are identical, `readonly` modifiers included, which
+// plain assignability ignores.
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+// The keys of `P` a write may name: every key but a `readonly` one, which the
+// engine refuses to set.
+type WritableKey<P> = {
+  [K in keyof P]-?: Identical<{ [Q in K]: P[K] }, { -readonly [Q in K]: P[K] }> extends true
+    ? K
+    : never;
+}[keyof P];
+
 declare global {
   namespace go {
     interface GoPropertyOptions {
+      /** **⚠️ 1-based index into an array property; passed to Defold unchanged.** */
       index?: number;
-      key?: Hash;
-      keys?: Record<string | number, unknown>;
+      key?: Hash | string;
+      keys?: (Hash | string)[];
     }
 
     /**
@@ -20,9 +34,9 @@ declare global {
      * @param url - url of the game object or component having the property
      * @param property - id of the property to retrieve
      * @param options - optional options table
-     * - index number index into array property (1 based)
-     * - key hash name of internal property
-     * - keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
+     * - index number **⚠️ 1-based index into an array property; passed to Defold unchanged.**
+     * - key hash or string name of internal property
+     * - keys array of hashes or strings identifying internal component resources (e.g. a particle fx emitter, see examples below)
      * @returns the value of the specified property
      * @example
      * ```ts
@@ -52,20 +66,21 @@ declare global {
      *
      * @param url - url of the game object or component having the property
      * @param property - id of the property to set
-     * @param value - the value to set
+     * @param value - the value to set, or an array of vector4 to set a material property array
      * @param options - optional options table
-     * - index integer index into array property (1 based)
-     * - key hash name of internal property
-     * - keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)
+     * - index integer **⚠️ 1-based index into an array property; passed to Defold unchanged.**
+     * - key hash or string name of internal property
+     * - keys array of hashes or strings identifying internal component resources (e.g. a particle fx emitter, see examples below)
      * @example
      * ```ts
      * go.set("#sprite", "tint", vmath.vector4(1, 0, 0, 1));
      * // Name the target component to gate the value to its property type. The
-     * // empty call applies the type argument, then the inner call infers the key:
+     * // empty call applies the type argument, then the inner call infers the key.
+     * // A read-only property such as "animation" is not a key it accepts:
      * go.set<sprite.properties>()("#sprite", "playback_rate", 2);
      * ```
      */
-    function set<P>(): <K extends keyof P>(
+    function set<P>(): <K extends WritableKey<P>>(
       url: SceneAddress | Hash | Url,
       property: K,
       value: P[K],
@@ -80,11 +95,14 @@ declare global {
     function set(
       url: SceneAddress | Hash | Url,
       property: string | Hash,
-      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion,
+      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Vector4[],
       options?: GoPropertyOptions,
     ): void;
     /**
-     * Registers a Defold editor script property (deprecated escape hatch).
+     * Registers a script property, which the Defold editor exposes on every game
+     * object and collection that uses the script. Defold accepts the call only at
+     * the top level of the script, outside callbacks such as `init` and `update`.
+     * A `string` default needs Defold 1.13.2 or later.
      *
      * @deprecated Don't call `go.property` yourself. Declare the property in
      * `defineScript({ properties })` — that is the only form that types it onto
@@ -121,5 +139,7 @@ declare global {
     function property(name: string, value: Vector4): ScriptProperty<Vector4>;
     /** @deprecated Declare quaternions via the `defineScript({ properties })` field. */
     function property(name: string, value: Quaternion): ScriptProperty<Quaternion>;
+    /** @deprecated Declare text via the `defineScript({ properties })` field; needs Defold 1.13.2. */
+    function property(name: string, value: string): ScriptProperty<string>;
   }
 }