@defold-typescript/types 0.32.1 → 0.33.1

package/src/emit-dts.ts

@@ -288,6 +288,69 @@ export const PROPERTY_TYPE_CORRECTIONS: ReadonlyMap<string, PropertyTypeCorrecti
   ],
 ]);
 
+// A parameter the ref-doc metadata marks required while the same element's prose
+// or examples show it being omitted. `is_optional` is the only optionality
+// signal the emitter has, and upstream leaves it `False` on slots its own
+// examples skip — so the emitted declaration rejects the call the docs teach.
+//
+// Keyed `<element>:param:<slot>`, the shape `tableSlotKey` builds, so a
+// same-named slot on another element is untouched. The value is the upstream
+// evidence for that one entry: the example call that omits it, or the doc phrase
+// that names it optional. Both emitted shapes follow from one predicate — a
+// trailing slot becomes `slot?:`, an interior one `slot: T | undefined`.
+//
+// Demonstrated omissions only. `resource.set_texture`'s buffer and
+// `sys.load_buffer_async`'s status_callback read as optional but every upstream
+// example passes them, so neither is a correction candidate.
+export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
+  [
+    "resource.create_texture:param:buffer",
+    'example `resource.create_texture("/my_custom_texture.texturec", tparams)`; "optional buffer of precreated pixel data"',
+  ],
+  ["resource.create_texture_async:param:buffer", '"optional buffer of precreated pixel data"'],
+  [
+    "resource.create_texture_async:param:callback",
+    'example `resource.create_texture_async("/my_texture.texturec", tparams, tbuffer)`',
+  ],
+  [
+    "gui.new_texture:param:flip",
+    'example `gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h))`',
+  ],
+  [
+    "gui.set_texture_data:param:flip",
+    'example `gui.set_texture_data("dynamic_tx", w, h, "rgb", string.rep(orange, w * h))`',
+  ],
+  ["sys.set_engine_throttle:param:cooldown", "example `sys.set_engine_throttle(false)`"],
+  [
+    "b2d.fixture.set_shape:param:update_mass",
+    '2 of 3 examples omit it; "The body mass is not updated unless update_mass is true"',
+  ],
+  [
+    "b2d.shape.ray_cast:param:max_fraction",
+    '"optional maximum translation fraction, defaults to 1"',
+  ],
+  ["iap.buy:param:options", '"optional parameters as properties"'],
+  ...(
+    [
+      "create_distance",
+      "create_mouse",
+      "create_prismatic",
+      "create_revolute",
+      "create_weld",
+      "create_wheel",
+      "create_friction",
+      "create_rope",
+      "create_pulley",
+      "create_gear",
+      "create_motor",
+      "create_filter",
+    ] as const
+  ).map(
+    (name) =>
+      [`b2d.joint.${name}:param:definition`, '"optional definition"'] as readonly [string, string],
+  ),
+]);
+
 // FQN-keyed allowlist of the `types.is_*` checks that genuinely narrow their
 // argument, mapped to the `DEFOLD_TYPE_MAP` token whose interface they prove.
 // Emitting these as user-defined type guards (`var_ is Vector3`) is the only way
@@ -2013,7 +2076,7 @@ function memberSignature(
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
-  const cutoff = trailingOptionalCutoff(original);
+  const cutoff = trailingOptionalCutoff(original, elementName);
   const varargIndex = original.findIndex(isVarargParameter);
   const positional = (varargIndex === -1 ? original : original.slice(0, varargIndex)).map((p, i) =>
     emitParameter(p, i, i >= cutoff, mapType, resolver, elementName, urlParameters),
@@ -2124,15 +2187,31 @@ export function summaryFor(brief: string, description: string): string {
   return description.trim() !== "" ? description : brief;
 }
 
-function isDocOptional(p: ApiParameter): boolean {
+export function isMarkedOptional(p: ApiParameter): boolean {
   return p.isOptional || p.types.includes("nil");
 }
 
-function trailingOptionalCutoff(params: readonly ApiParameter[]): number {
+// The one optionality predicate, in two halves: the ref-doc's own marking
+// (`isMarkedOptional`, which the correction provenance guards read alone to
+// tell which targets still need a correction) and the OPTIONAL_SLOT_CORRECTIONS
+// entries that override it. Both emitted shapes read it — the trailing `?`
+// through `trailingOptionalCutoff` and the interior `| undefined` through
+// `emitParameter` — so a correction threaded in here reaches both without a
+// second copy of the rule. The fidelity audit reads it too, to tell which slots
+// the emitted surface still makes required.
+export function isDocOptional(p: ApiParameter, elementName: string): boolean {
+  if (isMarkedOptional(p)) return true;
+  return OPTIONAL_SLOT_CORRECTIONS.has(tableSlotKey(elementName, "param", p.name));
+}
+
+export function trailingOptionalCutoff(
+  params: readonly ApiParameter[],
+  elementName: string,
+): number {
   let cutoff = params.length;
   for (let i = params.length - 1; i >= 0; i -= 1) {
     const p = params[i];
-    if (p && isDocOptional(p)) cutoff = i;
+    if (p && isDocOptional(p, elementName)) cutoff = i;
     else break;
   }
   return cutoff;
@@ -2230,7 +2309,7 @@ function emitParameter(
   // projection cannot mark it) keeps its optionality as `| undefined` — TSTL
   // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
   // `?` form; required params are untouched.
-  const interiorOptional = !optional && isDocOptional(p) ? " | undefined" : "";
+  const interiorOptional = !optional && isDocOptional(p, elementName) ? " | undefined" : "";
   return `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`;
 }
 

package/src/msg-overloads.d.ts

@@ -48,6 +48,13 @@ declare global {
      *
      * The two-arg form `msg.url(socket, path)` is a runtime error.
      *
+     * `socket` may be `undefined` (Lua `nil`), which addresses the current
+     * game world, exactly as the runtime's own examples do.
+     *
+     * The one-argument form's `urlstring` may likewise be `undefined` (Lua
+     * `nil`), which the ref-doc calls equivalent to `msg.url()` — the URL of the
+     * current script.
+     *
      * In the same world, address a sibling **relatively** — by bare id
      * (`msg.url("camera")`), absolute path (`msg.url("/camera")`), or
      * component (`msg.url("#main")`). The `socket:` prefix only crosses
@@ -58,6 +65,9 @@ declare global {
      * // No-arg, then take the current game object's URL.
      * const self: Url = msg.url();
      *
+     * // An `undefined` argument is the no-arg form spelled out.
+     * const alsoSelf: Url = msg.url(undefined);
+     *
      * // A sibling in the same world — bare id, no socket prefix.
      * const sibling: Url = msg.url("camera");
      *
@@ -69,10 +79,17 @@ declare global {
      *
      * // Crossing into a proxy-loaded world — `socket` is the world name.
      * const proxied: Url = msg.url(hash("level1"), hash("/door"), hash("script"));
+     *
+     * // An `undefined` socket addresses the current game world.
+     * const currentWorld: Url = msg.url(undefined, hash("/door"), hash("script"));
      * ```
      */
     function url(): Url;
-    function url(urlstring: SceneAddress): Url;
-    function url(socket: string | Hash, path: string | Hash, fragment: string | Hash): Url;
+    function url(urlstring: SceneAddress | undefined): Url;
+    function url(
+      socket: string | Hash | undefined,
+      path: string | Hash,
+      fragment: string | Hash,
+    ): Url;
   }
 }

package/src/optional-correction-provenance.ts

@@ -0,0 +1,126 @@
+import { type ApiModule, parseDefoldApiDoc } from "./api-doc";
+import { isMarkedOptional } from "./emit-dts";
+
+export interface ProvenanceSurface {
+  readonly target: string;
+  readonly namespace: string;
+  readonly doc: unknown;
+}
+
+export interface CorrectionProvenance {
+  readonly key: string;
+  readonly sightedIn: readonly string[];
+  readonly neededBy: readonly string[];
+  readonly markedIn: readonly string[];
+}
+
+interface ManifestEntry {
+  readonly namespace: string;
+  readonly doc: unknown;
+}
+
+interface VersionedManifestEntry extends ManifestEntry {
+  readonly versionId: string;
+  readonly editor?: boolean;
+}
+
+// Every runtime module regen emits through the global correction table: the
+// default target's manifest plus every older generated target's. Editor-VM
+// entries are outside the scope the corrections cover.
+export function retainedSurfaces(
+  defaultTarget: string,
+  defaultManifest: readonly ManifestEntry[],
+  versionedManifest: readonly VersionedManifestEntry[],
+): ProvenanceSurface[] {
+  return [
+    ...defaultManifest.map((entry) => ({
+      target: defaultTarget,
+      namespace: entry.namespace,
+      doc: entry.doc,
+    })),
+    ...versionedManifest
+      .filter((entry) => entry.editor !== true)
+      .map((entry) => ({ target: entry.versionId, namespace: entry.namespace, doc: entry.doc })),
+  ];
+}
+
+const PARAM_SEPARATOR = ":param:";
+
+// A target needs a correction while any sighting of the slot there is unmarked,
+// so an overload that marks it in one declaration and not another still needs
+// it. The correction can go only once no target needs it.
+export function correctionProvenance(
+  keys: readonly string[],
+  surfaces: readonly ProvenanceSurface[],
+): CorrectionProvenance[] {
+  const parsed = new Map<ProvenanceSurface, ApiModule>();
+  const parse = (surface: ProvenanceSurface): ApiModule => {
+    let module = parsed.get(surface);
+    if (!module) {
+      module = parseDefoldApiDoc(surface.doc);
+      parsed.set(surface, module);
+    }
+    return module;
+  };
+
+  return keys.map((key) => {
+    const separator = key.lastIndexOf(PARAM_SEPARATOR);
+    if (separator < 0) throw new Error(`correctionProvenance: malformed key ${key}`);
+    const element = key.slice(0, separator);
+    const slot = key.slice(separator + PARAM_SEPARATOR.length);
+    const namespace = element.slice(0, element.lastIndexOf("."));
+
+    const markedByTarget = new Map<string, boolean>();
+    for (const surface of surfaces) {
+      if (surface.namespace !== namespace) continue;
+      for (const fn of parse(surface).functions) {
+        if (fn.name !== element) continue;
+        for (const parameter of fn.parameters) {
+          if (parameter.name !== slot) continue;
+          const marked = markedByTarget.get(surface.target) ?? true;
+          markedByTarget.set(surface.target, marked && isMarkedOptional(parameter));
+        }
+      }
+    }
+
+    const sightedIn = [...markedByTarget.keys()].sort();
+    return {
+      key,
+      sightedIn,
+      neededBy: sightedIn.filter((target) => markedByTarget.get(target) === false),
+      markedIn: sightedIn.filter((target) => markedByTarget.get(target) === true),
+    };
+  });
+}
+
+// Reads the raw doc rather than `parseDefoldApiDoc`, which folds an absent
+// `is_optional` into `isOptional: false` and so erases the difference between a
+// parameter upstream calls required and one it never classified at all.
+export function whollyUnmarkedNamespaces(
+  surfaces: readonly ProvenanceSurface[],
+): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const surface of surfaces) {
+    const namespaces = out.get(surface.target) ?? [];
+    out.set(surface.target, namespaces);
+    const parameters = rawFunctionParameters(surface.doc);
+    if (parameters.length > 0 && parameters.every((parameter) => !("is_optional" in parameter))) {
+      namespaces.push(surface.namespace);
+    }
+  }
+  for (const namespaces of out.values()) namespaces.sort();
+  return out;
+}
+
+function rawFunctionParameters(doc: unknown): Record<string, unknown>[] {
+  if (!isRecord(doc) || !Array.isArray(doc.elements)) return [];
+  return doc.elements.flatMap((element) =>
+    isRecord(element) && element.type === "FUNCTION" && Array.isArray(element.parameters)
+      ? element.parameters.filter(isRecord)
+      : [],
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}