@defold-typescript/library-types 0.23.0 → 0.25.0

package/scripts/fidelity-floor.ts

@@ -0,0 +1,178 @@
+/**
+ * A one-sided coverage ratchet over the committed `fidelity/*.json` reports.
+ *
+ * Each emitting lane already round-trips its committed report against a freshly
+ * built one, which proves the report matches what the pipeline builds *today* —
+ * but a regeneration that lowers coverage rewrites the report too, so the drop
+ * lands silently. `fidelity-floor.json` pins each report's coverage from the
+ * outside: `regen` never touches it, so the only way a floor moves is the
+ * explicit, monotone `--raise` below — which also makes it the one hand-editable
+ * input here, so it is parsed under a validating contract (`parseFloors`).
+ *
+ * Reports are keyed by package-root-relative POSIX path, not by namespace:
+ * `fidelity/openapi/nakama.nakama.json` reports `namespace: "nakama"`, and two
+ * lanes emitting the same namespace would collide on a namespace key.
+ *
+ * The walk is universal over `fidelity/` with one carve-out: `fidelity/authored/`
+ * holds *surface* parity, not *type-token* coverage. Those reports have no
+ * `totalTypeTokens` to be a fraction of, and their coverage means something else —
+ * upstream members declared at the right arity, from `authored-parity.ts`. They get
+ * their own ratchet in `authored-parity-floor.json`, so folding them in here would
+ * only mean two incompatible denominators under one floor manifest. That manifest
+ * also ratchets *two* axes per key (`callableCoverage` and `fieldCoverage`, never
+ * averaged), which a flat one-ratio-per-key manifest cannot express — a second,
+ * independent reason the two do not merge. Its entries are parsed by
+ * `parseAuthoredFloors`, not by `parseFloors` below.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export const FIDELITY_DIR = "fidelity";
+/** Directory name under `fidelity/` the token-coverage walk skips — see the
+ * module note; ratcheted by `authored-parity-floor.json` instead. */
+export const AUTHORED_PARITY_DIRNAME = "authored";
+export const FLOOR_MANIFEST_FILE = "fidelity-floor.json";
+export const FLOOR_RAISE_COMMAND = "bun run --cwd packages/library-types fidelity:floor";
+
+export interface FidelityFloorReport {
+  coverage: number;
+  totalMembers: number;
+  totalTypeTokens: number;
+}
+
+function numberField(raw: Record<string, unknown>, field: string, path: string): number {
+  const value = raw[field];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${path}: expected a finite numeric "${field}", got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+function walkJsonFiles(dir: string, prefix: string, out: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      if (prefix === "" && entry.name === AUTHORED_PARITY_DIRNAME) continue;
+      walkJsonFiles(join(dir, entry.name), rel, out);
+    } else if (entry.name.endsWith(".json")) out.push(rel);
+  }
+}
+
+/**
+ * Every committed fidelity report under `fidelity/`, at any depth, keyed by its
+ * package-root-relative POSIX path and sorted by that key. Reads only — the walk
+ * is the enumeration the gate trusts, so a lane that emits into a nested
+ * directory (`fidelity/openapi/`) is picked up without registration.
+ */
+export function collectFidelityReports(root: string): Record<string, FidelityFloorReport> {
+  const dir = join(root, FIDELITY_DIR);
+  if (!existsSync(dir)) return {};
+  const relatives: string[] = [];
+  walkJsonFiles(dir, "", relatives);
+  const reports: Record<string, FidelityFloorReport> = {};
+  for (const rel of relatives.sort()) {
+    const key = `${FIDELITY_DIR}/${rel}`;
+    const raw = JSON.parse(readFileSync(join(dir, rel), "utf8")) as Record<string, unknown>;
+    reports[key] = {
+      coverage: numberField(raw, "coverage", key),
+      totalMembers: numberField(raw, "totalMembers", key),
+      totalTypeTokens: numberField(raw, "totalTypeTokens", key),
+    };
+  }
+  return reports;
+}
+
+// `JSON.stringify` renders NaN and Infinity as `null` and returns `undefined` for
+// `undefined`, both of which would misreport the value the manifest actually holds.
+function describeFloor(value: unknown): string {
+  if (typeof value === "number") return String(value);
+  return JSON.stringify(value) ?? String(value);
+}
+
+/**
+ * The floor manifest's parse-time contract: a plain object of finite numbers in
+ * `[0, 1]`. Every consuming assertion compares coercively, so an unvalidated
+ * `null` or `false` floor would pass `floor !== undefined` and fail every
+ * `coverage < floor` comparison — switching that report's ratchet off silently.
+ * Key order is the writer's contract and is preserved here, not sorted.
+ */
+export function parseFloors(raw: unknown, path: string): Record<string, number> {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${path}: expected a JSON object of floors, got ${describeFloor(raw)}`);
+  }
+  const floors: Record<string, number> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+      throw new Error(
+        `${path}: floor "${key}" must be a finite number in [0, 1], got ${describeFloor(value)}`,
+      );
+    }
+    floors[key] = value;
+  }
+  return floors;
+}
+
+/** The committed floor manifest, or an empty manifest when it does not exist yet. */
+export function readFloors(root: string): Record<string, number> {
+  const path = join(root, FLOOR_MANIFEST_FILE);
+  if (!existsSync(path)) return {};
+  return parseFloors(JSON.parse(readFileSync(path, "utf8")), FLOOR_MANIFEST_FILE);
+}
+
+/**
+ * The next floor manifest: each report's floor rises to its current coverage and
+ * never falls, a report with no floor gains one, and a floor whose report is gone
+ * is dropped. Monotone by construction — no code path here writes a smaller
+ * number, so a regression can only ever be reported by the gate, never absorbed.
+ */
+export function raiseFloors(
+  floors: Record<string, number>,
+  reports: Record<string, FidelityFloorReport>,
+): Record<string, number> {
+  const next: Record<string, number> = {};
+  for (const key of Object.keys(reports).sort()) {
+    const existing = floors[key];
+    const { coverage } = reports[key] as FidelityFloorReport;
+    next[key] = existing === undefined ? coverage : Math.max(existing, coverage);
+  }
+  return next;
+}
+
+// `fidelity-floor.json` sits at the package root, so unlike the reports under
+// `fidelity/` it is not biome-excluded and must match Biome's formatting.
+function biomeFormatJson(raw: string): string {
+  const out = Bun.spawnSync(
+    ["bunx", "biome", "format", `--stdin-file-path=${FLOOR_MANIFEST_FILE}`],
+    {
+      stdin: Buffer.from(raw),
+    },
+  );
+  if (out.exitCode !== 0) {
+    throw new Error(`biome format failed: ${out.stderr.toString()}`);
+  }
+  return out.stdout.toString();
+}
+
+if (import.meta.main) {
+  const root = resolve(import.meta.dir, "..");
+  const reports = collectFidelityReports(root);
+  const current = readFloors(root);
+  const next = raiseFloors(current, reports);
+
+  if (process.argv.includes("--raise")) {
+    for (const key of Object.keys(next)) {
+      const before = current[key];
+      if (before === undefined) console.log(`${key}: (new) -> ${next[key]}`);
+      else if (before !== next[key]) console.log(`${key}: ${before} -> ${next[key]}`);
+    }
+    for (const key of Object.keys(current)) {
+      if (next[key] === undefined) console.log(`${key}: dropped (no such report)`);
+    }
+    const path = join(root, FLOOR_MANIFEST_FILE);
+    writeFileSync(path, biomeFormatJson(JSON.stringify(next)));
+    console.log(`wrote ${path}`);
+  } else {
+    console.log(JSON.stringify(next, null, 2));
+  }
+}

package/scripts/import-upstream-docs.ts

@@ -0,0 +1,125 @@
+/**
+ * Carrying upstream's own LuaDoc into the authored lane's api-doc, for members the
+ * fork documents nowhere.
+ *
+ * `parse-lua-surface.ts` already reads each upstream member's `---` block and
+ * `authored-parity.ts` already counts how many of them the fork drops, so the text
+ * exists on one side of the pipeline and was thrown away before the docs-site saw
+ * it. This module is the merge, and it runs at api-doc lowering rather than in the
+ * vendored `.d.ts`: writing upstream prose into `fixtures/authored/*.d.ts` would
+ * still pass the forked-vs-generated identity diff while destroying what that diff
+ * exists to prove — that the emitted surface *is* the vendored fork — and imported
+ * prose would be indistinguishable from fork prose forever after.
+ *
+ * Three rules carry the whole merge:
+ *
+ * - **Fork prose always wins.** An element the fork gave either a `brief` or a
+ *   `description` is returned untouched and gains no `docSource`, so authoring the
+ *   fork's own doc-comment is how a member opts out. There is no exclusion list:
+ *   the only thing one would add is "show no prose at all for a member upstream
+ *   documented", which is worse than writing the correct brief.
+ * - **Tags never come with the summary.** Every block in this corpus is a summary
+ *   followed by `@param`/`@return` lines, and a tag's continuation lines carry no
+ *   marker of their own, so truncating at the *first* `@` line is what keeps
+ *   LuaDoc-derived types and parameter names out of the api-doc.
+ * - **A brief never restates its own symbol.** A leading line that is exactly the
+ *   element's name is upstream's heading, not prose, and is dropped before the brief is
+ *   taken. That is the importer's knowledge, not `summarizeLuaDoc`'s, which stays a pure
+ *   block-to-prose function.
+ */
+
+import type { LuaMember } from "./parse-lua-surface";
+
+/** One `api-doc/<namespace>.json` element, open at the edges: this module reads the
+ * four keys the merge turns on and passes every other key through in place. */
+export interface ApiDocElement {
+  type: string;
+  name: string;
+  global?: boolean;
+  brief?: string;
+  description?: string;
+  docSource?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * The prose half of a LuaDoc block: its lines up to the first whose trimmed text
+ * starts with `@`, rejoined and trimmed. Empty for a block that is only tags.
+ *
+ * Interior newlines and blank lines survive. Markdown collapses a soft break at
+ * render time, so no unwrapping is done and the imported description stays
+ * upstream's own text.
+ */
+export function summarizeLuaDoc(doc: string): string {
+  const summary: string[] = [];
+  for (const line of doc.split("\n")) {
+    if (line.trim().startsWith("@")) break;
+    summary.push(line);
+  }
+  return summary.join("\n").trim();
+}
+
+/** The summary without a leading line that is only the element's own name. nakama writes
+ * `--- <member_name>` above the real summary, and `briefOf` takes the first line, so
+ * leaving it in ships a brief that restates the symbol it sits under. The comparison is
+ * exact: a first line that merely mentions the name is prose and survives. */
+function withoutNameLine(summary: string, name: string): string {
+  const [first, ...rest] = summary.split("\n");
+  return (first as string).trim() === name ? rest.join("\n").trim() : summary;
+}
+
+/** The element with upstream's summary in place, `docSource` inserted immediately
+ * after `description` by copying the element's own entries in order rather than
+ * assigning onto it — the key order is what the committed api-doc golden diffs on. */
+function withImportedDoc(element: ApiDocElement, summary: string): ApiDocElement {
+  const brief = summary.split("\n")[0]?.trim() ?? "";
+  const imported: ApiDocElement = { type: element.type, name: element.name };
+  let placedBrief = false;
+  let placedDescription = false;
+  for (const [key, value] of Object.entries(element)) {
+    if (key === "type" || key === "name") continue;
+    if (key === "brief") {
+      imported.brief = brief;
+      placedBrief = true;
+    } else if (key === "description") {
+      imported.description = summary;
+      imported.docSource = "upstream";
+      placedDescription = true;
+    } else imported[key] = value;
+  }
+  if (!placedDescription) {
+    imported.description = summary;
+    imported.docSource = "upstream";
+  }
+  if (!placedBrief) imported.brief = brief;
+  return imported;
+}
+
+/**
+ * The api-doc element list with upstream prose merged in, as a new list.
+ *
+ * An element is imported when it is a `FUNCTION` or a `VARIABLE` — the two kinds
+ * `authored-parity.ts` compares, a `TYPEDEF` being a type rather than a runtime
+ * member — is not `global: true`, has an empty `brief` *and* an empty
+ * `description`, matches an upstream member by exact name, and that member's
+ * summary survives tag stripping. Every other element is returned unchanged.
+ *
+ * The name match is exact on purpose: a namespace-qualified api-doc name
+ * (`bridge.bridge`) never matches a bare upstream name, which is the same non-match
+ * the parity pass makes.
+ */
+export function importUpstreamDocs(
+  elements: readonly ApiDocElement[],
+  members: ReadonlyMap<string, LuaMember>,
+): ApiDocElement[] {
+  return elements.map((element) => {
+    if (element.type !== "FUNCTION" && element.type !== "VARIABLE") return element;
+    if (element.global === true) return element;
+    if ((element.brief ?? "") !== "" || (element.description ?? "") !== "") return element;
+    const member = members.get(element.name);
+    if (member === undefined) return element;
+    const summary = withoutNameLine(summarizeLuaDoc(member.doc), element.name);
+    if (summary === "") return element;
+    return withImportedDoc(element, summary);
+  });
+}

package/scripts/lower-api-doc.ts

@@ -15,6 +15,7 @@
 
 import {
   buildModelContext,
+  type ExternalTypeRef,
   isPublicField,
   isPublicMethod,
   mapTypes,
@@ -67,9 +68,13 @@ function functionElement(method: LibraryMethod, ctx: MapContext): Record<string,
       parameterElement(param, optionalFlags[index] ?? false, fnCtx),
     ),
     returnvalues: method.returns.map((ret) => returnElement(ret, fnCtx)),
+    ...(method.deprecated !== undefined ? { deprecated: method.deprecated } : {}),
   };
 }
 
+// No `deprecated` spread here or on `variableElement`: both take a `LibraryField`,
+// and a one-line `---@field` has no slot for a block tag in this dialect, so a
+// property can never carry one.
 function propertyElement(field: LibraryField, ctx: MapContext): Record<string, unknown> {
   return {
     name: field.name,
@@ -93,9 +98,17 @@ function variableElement(field: LibraryField, ctx: MapContext): Record<string, u
 
 export function lowerLibraryModel(
   model: LibraryModel,
-  { namespace, typeRenames }: { namespace: string; typeRenames?: Record<string, string> },
+  {
+    namespace,
+    typeRenames,
+    externalTypes,
+  }: {
+    namespace: string;
+    typeRenames?: Record<string, string>;
+    externalTypes?: Record<string, ExternalTypeRef> | undefined;
+  },
 ): unknown {
-  const ctx = buildModelContext(model, typeRenames);
+  const ctx = buildModelContext(model, typeRenames, externalTypes);
   const elements: Record<string, unknown>[] = [];
 
   for (const fn of model.moduleFunctions) {
@@ -125,11 +138,16 @@ export function lowerLibraryModel(
       name: sanitizeTypeName(iface.name),
       ...(functions.length > 0 ? { functions } : {}),
       ...(properties.length > 0 ? { properties } : {}),
+      ...(iface.deprecated !== undefined ? { deprecated: iface.deprecated } : {}),
     });
   }
 
   for (const alias of model.aliases) {
-    elements.push({ type: "TYPEDEF", name: sanitizeTypeName(alias.name) });
+    elements.push({
+      type: "TYPEDEF",
+      name: sanitizeTypeName(alias.name),
+      ...(alias.deprecated !== undefined ? { deprecated: alias.deprecated } : {}),
+    });
   }
 
   // The module's own `@class` carries the library's summary; use it as the page

package/scripts/luals-fidelity.ts

@@ -10,7 +10,12 @@
  * sorted-unique token list so the gap is visible instead of silent.
  */
 
-import { isPublicField, isPublicMethod } from "./emit-library-dts";
+import {
+  buildModelContext,
+  type ExternalTypeRef,
+  isPublicField,
+  isPublicMethod,
+} from "./emit-library-dts";
 import { type MapContext, mapLualsType, scopeGenerics } from "./map-luals-types";
 import type { LibraryGeneric, LibraryModel } from "./parse-luals";
 
@@ -29,22 +34,22 @@ function round3(value: number): number {
 }
 
 /**
- * Build the fidelity report for one namespace. `knownNames` is drawn from the
- * model's own interface and alias names so a reference to a sibling library type
- * resolves rather than falling to `unknown`. Every field, every param and return
- * of every method and module function, and every alias expression is mapped;
- * `undocumentedMembers` counts fields/methods/moduleFunctions whose doc or brief
- * is empty. Deterministic; no I/O.
+ * Build the fidelity report for one namespace. Tokens map through the same
+ * `buildModelContext` the emitter and the api-doc lowering use, so all three agree
+ * on what resolves — the model's own interface and alias names, plus the
+ * `externalTypes` tokens reached through a cross-module import — and all three
+ * reject an external alias that collides with a declared name. Every field, every
+ * param and return of every method and module function, and every alias expression
+ * is mapped; `undocumentedMembers` counts fields/methods/moduleFunctions whose doc
+ * or brief is empty. Deterministic; no I/O.
  */
 export function buildFidelityReport(
   namespace: string,
   model: LibraryModel,
   typeRenames: Record<string, string>,
+  externalTypes?: Record<string, ExternalTypeRef>,
 ): FidelityReport {
-  const knownNames = new Set<string>();
-  for (const iface of model.interfaces) knownNames.add(iface.name);
-  for (const alias of model.aliases) knownNames.add(alias.name);
-  const ctx: MapContext = { knownNames, typeRenames };
+  const ctx = buildModelContext(model, typeRenames, externalTypes);
 
   let totalMembers = 0;
   let totalTypeTokens = 0;

package/scripts/map-luals-types.ts

@@ -13,6 +13,7 @@
  * verbatim and the emitter sanitizes it later.
  */
 
+import { luaMultiReturn } from "@defold-typescript/types";
 import { CORE_TYPE_RENAMES } from "./sync-library-types";
 
 export interface MapContext {
@@ -52,6 +53,24 @@ const SCALARS: Readonly<Record<string, string>> = {
   any: "unknown",
 };
 
+/**
+ * LuaLS's bare `function` — any callable, signature unspecified. Params are `any[]`
+ * because under `strictFunctionTypes` an `unknown[]` rest would reject every concrete
+ * callback a consumer passes; the return stays `unknown` because return position is
+ * covariant, so `any` there would only leak unchecked values into call sites.
+ */
+const CALLABLE_UNSPECIFIED = "(...args: any[]) => unknown";
+
+/**
+ * LuaLS's two placeholders: the throwaway param name `_`, and a bare `...` in vararg
+ * or return position. Neither declares a type at all, so lowering it to `unknown`
+ * loses nothing an author wrote — the same reasoning that already exempts `any` from
+ * the fallback count. The boundary is deliberate: an untyped `self` or `ctx` *is* an
+ * upstream omission and stays recorded.
+ */
+const LUALS_THROWAWAY_PARAM = "_";
+export const LUALS_VARARG_TOKEN = "...";
+
 /**
  * Split `s` on every top-level occurrence of the single-character `sep`, honoring
  * bracket depth and double-quoted string literals so a separator nested inside
@@ -146,21 +165,18 @@ function functionParts(
   const paramList = params
     .map((raw) => raw.trim())
     .map((part) => {
-      if (part.startsWith("...")) {
+      if (part.startsWith(LUALS_VARARG_TOKEN)) {
         const after = part.slice(3).trim();
-        let element: string;
-        if (after.startsWith(":")) {
-          element = mapToken(after.slice(1).trim(), ctx, unknowns);
-        } else {
-          element = "unknown";
-          unknowns.push("...");
-        }
+        const element = after.startsWith(":")
+          ? mapToken(after.slice(1).trim(), ctx, unknowns)
+          : "unknown";
         return `...args: ${needsArrayParens(element) ? `(${element})[]` : `${element}[]`}`;
       }
       const colon = splitTopLevel(part, ":");
       if (colon.length < 2) {
-        // Untyped param (`self`, `_`, `ctx`): a recorded gap, not a silent `any`.
-        unknowns.push(part);
+        // Untyped param (`self`, `ctx`): a recorded gap, not a silent `any`. A bare `_`
+        // is LuaLS's deliberate throwaway and records nothing.
+        if (part !== LUALS_THROWAWAY_PARAM) unknowns.push(part);
         return `${part}: unknown`;
       }
       const name = colon[0]?.trim() ?? "";
@@ -177,8 +193,11 @@ function functionParts(
     if (retTokens.length === 1) {
       ret = mapToken(retTokens[0] as string, ctx, unknowns);
     } else if (retTokens.length > 1) {
-      const inner = retTokens.map((r) => mapToken(r, ctx, unknowns)).join(", ");
-      ret = `LuaMultiReturn<[${inner}]>`;
+      const restTail = retTokens.at(-1) === LUALS_VARARG_TOKEN;
+      ret = luaMultiReturn(
+        retTokens.map((r) => mapToken(r, ctx, unknowns)),
+        restTail,
+      );
     }
   }
   return { paramList, ret };
@@ -215,15 +234,11 @@ function mapToken(raw: string, ctx: MapContext, unknowns: string[]): string {
 
   if (token === "") return "unknown";
 
-  // Optional suffix.
-  if (token.length > 1 && token.endsWith("?")) {
-    const base = mapToken(token.slice(0, -1), ctx, unknowns);
-    const members = splitTopLevel(base, "|").map((m) => m.trim());
-    return members.includes("undefined") ? base : `${base} | undefined`;
-  }
-
-  // A `fun(...)` whose return follows the `)` keeps its return-type `|` inside the
-  // function; splitting the union first would cut `fun(): a|b` into `(fun) | b`.
+  // A `fun(...)` whose return follows the `)` keeps its return-type `|` and `?` inside
+  // the function; splitting the union first would cut `fun(): a|b` into `(fun) | b`, and
+  // peeling the optional suffix first would turn `fun(): number?` — a function with an
+  // optional *return* — into an optional function. The whole-function optional is spelled
+  // with explicit parentheses, `(fun(): number)?`, which does not match here.
   // `fun()|nil` (a `|` right after the `)`) falls through to the union split.
   if (/^fun\s*\(/.test(token)) {
     const close = matchBracket(token, token.indexOf("("));
@@ -233,6 +248,13 @@ function mapToken(raw: string, ctx: MapContext, unknowns: string[]): string {
     }
   }
 
+  // Optional suffix.
+  if (token.length > 1 && token.endsWith("?")) {
+    const base = mapToken(token.slice(0, -1), ctx, unknowns);
+    const members = splitTopLevel(base, "|").map((m) => m.trim());
+    return members.includes("undefined") ? base : `${wrapForUnion(base)} | undefined`;
+  }
+
   // Top-level union.
   const unionParts = splitTopLevel(token, "|");
   if (unionParts.length > 1) {
@@ -263,6 +285,15 @@ function mapToken(raw: string, ctx: MapContext, unknowns: string[]): string {
   // String literal — passthrough.
   if (token.startsWith('"') && token.endsWith('"')) return token;
 
+  // Signature-less callable. Placed after every composite branch so `function[]`,
+  // `function|nil`, and `fun(cb: function)` route through those first.
+  if (token === "function") return CALLABLE_UNSPECIFIED;
+
+  // Placeholder vararg in return position — not a `SCALARS` entry, which maps real Lua
+  // type names. Sits beside the callable branch so `...[]` and `...|nil` reach their
+  // structural handlers first.
+  if (token === LUALS_VARARG_TOKEN) return "unknown";
+
   // Scalars.
   const scalar = SCALARS[token];
   if (scalar !== undefined) return scalar;