@defold-typescript/library-types 0.22.0 → 0.23.0

package/scripts/parse-luals.ts

@@ -16,6 +16,11 @@ export interface LibraryModel {
   interfaces: LibraryInterface[];
   aliases: LibraryAlias[];
   moduleFunctions: LibraryMethod[];
+  // The name of the `---@class` a `return <name>` at column 0 hands back as the module
+  // table. Its public fields are the module's own constants (`export const`s), not a
+  // standalone interface. Set only when a returned local resolves to an opened class,
+  // so a module with a plain returned table carries no key.
+  moduleObject?: string;
 }
 
 export interface LibraryInterface {
@@ -25,6 +30,16 @@ export interface LibraryInterface {
   fields: LibraryField[];
   methods: LibraryMethod[];
   brief: string;
+  // A class-level `---@overload fun(...)`, kept as its raw `fun(...)` token plus the
+  // trailing description. Present only on interfaces that declare one (like `extends`),
+  // so an interface without overloads carries no key. The emitter renders each as an
+  // interface call signature; the mapper maps the token to a `(params): ret` form.
+  overloads?: LibraryOverload[];
+}
+
+export interface LibraryOverload {
+  type: string;
+  doc: string;
 }
 
 export interface LibraryMethod {
@@ -33,6 +48,11 @@ export interface LibraryMethod {
   generics: LibraryGeneric[];
   params: LibraryParam[];
   returns: LibraryParam[];
+  // A standalone `---@local`/`---@private`/`---@protected`/`---@package` before the
+  // function declaration. Set only when marked (like a field's `visibility`), so an
+  // unmarked method carries no key. `local` has no `@field` analogue (LuaLS field
+  // scope has no `local`), so a method's visibility widens the field set with it.
+  visibility?: LibraryMethodVisibility;
 }
 
 export interface LibraryParam {
@@ -41,10 +61,17 @@ export interface LibraryParam {
   doc: string;
   isOptional: boolean;
   isVararg: boolean;
+  // True when the raw type token carries a top-level `nil` union member (`T|nil`),
+  // distinct from the literal trailing `?` that drives `isOptional`. Set only when
+  // true (like a field's `visibility`), so a non-nil-bearing param carries no key.
+  // The emitter's trailing-run rule treats `isOptional || isNilable` as omittable.
+  isNilable?: boolean;
 }
 
 export type LibraryFieldVisibility = "public" | "protected" | "private" | "package";
 
+export type LibraryMethodVisibility = LibraryFieldVisibility | "local";
+
 export interface LibraryField {
   name: string;
   types: string[];
@@ -69,9 +96,17 @@ interface Pending {
   params: LibraryParam[];
   returns: LibraryParam[];
   generics: LibraryGeneric[];
+  overloads: LibraryOverload[];
+  visibility?: LibraryMethodVisibility;
 }
 
-const emptyPending = (): Pending => ({ doc: [], params: [], returns: [], generics: [] });
+const emptyPending = (): Pending => ({
+  doc: [],
+  params: [],
+  returns: [],
+  generics: [],
+  overloads: [],
+});
 
 /**
  * Read a single raw type token from the head of `rest`, honoring bracket depth so
@@ -101,6 +136,170 @@ function readTypeToken(rest: string): { type: string; rest: string } {
   return { type: rest.slice(0, i), rest: rest.slice(i).trim() };
 }
 
+/** Index of the bracket matching the opener at `open`, or -1 if unbalanced. */
+function matchCloser(s: string, open: number): number {
+  const pairs: Record<string, string> = { "<": ">", "(": ")", "[": "]", "{": "}" };
+  const want = pairs[s[open] as string];
+  let depth = 0;
+  let inQuote = false;
+  for (let i = open; i < s.length; i++) {
+    const c = s[i];
+    if (inQuote) {
+      if (c === '"') inQuote = false;
+      continue;
+    }
+    if (c === '"') inQuote = true;
+    else if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") {
+      depth--;
+      if (depth === 0) return c === want ? i : -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * 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
+ * `<...>`, `(...)`, `[...]`, `{...}`, or a `"..."` literal does not split. A parser-
+ * local copy of the mapper's identical helper — the parser is upstream of the mapper
+ * and must not import it (`hasTopLevelNil`'s comment).
+ */
+function splitTopLevel(s: string, sep: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let inQuote = false;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (inQuote) {
+      if (c === '"') inQuote = false;
+      continue;
+    }
+    if (c === '"') inQuote = true;
+    else if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0 && c === sep) {
+      parts.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts;
+}
+
+/**
+ * Decompose a `fun(...)` token into a method's `params`/`returns`, dropping a leading
+ * `self`. Used for a function-local `---@class` member typed by `---@type fun(...)`:
+ * modeling it as a method (each param keeping its raw type token) rather than a field
+ * makes the emitter render a full-typed method instead of the lossy permissive hook
+ * `matchSelfHookField` would produce. An unbalanced token yields empty lists.
+ */
+function funToMethodParts(token: string): { params: LibraryParam[]; returns: LibraryParam[] } {
+  const open = token.indexOf("(");
+  const close = open === -1 ? -1 : matchCloser(token, open);
+  if (open === -1 || close === -1) return { params: [], returns: [] };
+  const paramsStr = token.slice(open + 1, close).trim();
+  const afterClose = token.slice(close + 1).trim();
+
+  const params: LibraryParam[] = [];
+  const rawParams = paramsStr === "" ? [] : splitTopLevel(paramsStr, ",");
+  for (const rawPart of rawParams) {
+    const part = rawPart.trim();
+    if (part === "") continue;
+    if (part.startsWith("...")) {
+      const after = part.slice(3).trim();
+      const type = after.startsWith(":") ? after.slice(1).trim() : "";
+      const vararg: LibraryParam = {
+        name: "...",
+        types: type ? [type] : [],
+        doc: "",
+        isOptional: false,
+        isVararg: true,
+      };
+      if (type && hasTopLevelNil(type)) vararg.isNilable = true;
+      params.push(vararg);
+      continue;
+    }
+    const colon = splitTopLevel(part, ":");
+    const rawName = (colon[0] ?? "").trim();
+    const typeExpr = colon.length >= 2 ? colon.slice(1).join(":").trim() : "";
+    const isOptional = rawName.endsWith("?");
+    const name = isOptional ? rawName.slice(0, -1) : rawName;
+    const param: LibraryParam = {
+      name,
+      types: typeExpr ? [typeExpr] : [],
+      doc: "",
+      isOptional,
+      isVararg: false,
+    };
+    if (typeExpr && hasTopLevelNil(typeExpr)) param.isNilable = true;
+    params.push(param);
+  }
+  if (params[0]?.name === "self") params.shift();
+
+  const returns: LibraryParam[] = [];
+  if (afterClose.startsWith(":")) {
+    const retStr = afterClose.slice(1).trim();
+    for (const raw of retStr === "" ? [] : splitTopLevel(retStr, ",")) {
+      const type = raw.trim();
+      if (type)
+        returns.push({ name: "", types: [type], doc: "", isOptional: false, isVararg: false });
+    }
+  }
+  return { params, returns };
+}
+
+/**
+ * True when the raw type token has a top-level `nil` union member (`T|nil`,
+ * `fun()|nil`) — the signal that a parameter is nil-bearing and can be emitted
+ * TS-optional. Bracket- and quote-depth aware so a `nil` nested in
+ * `table<...>`/`{...}`/a `"..."` literal does not count, and a `fun(...): ret|nil`
+ * return-union (whose `|nil` sits at depth 0 after the `)`) is recognized as the
+ * function's own return, not an outer nullable — only a `|nil` applied to the whole
+ * token flags the param. Self-contained: the parser is upstream of the mapper and
+ * must not import it.
+ */
+function hasTopLevelNil(rawToken: string): boolean {
+  let token = rawToken.trim();
+  while (token.startsWith("(") && matchCloser(token, 0) === token.length - 1) {
+    token = token.slice(1, -1).trim();
+  }
+  if (/^fun\s*\(/.test(token)) {
+    const close = matchCloser(token, token.indexOf("("));
+    if (
+      close !== -1 &&
+      token
+        .slice(close + 1)
+        .trim()
+        .startsWith(":")
+    )
+      return false;
+  }
+  // A type-suffix `T?` (`string?`, `fun()?`, `(a|b)?`) is nil-bearing. Placed after the
+  // fun-return guard so a nullable return (`fun(): a|nil`, `fun(): string?`) never flags.
+  if (token.endsWith("?")) return true;
+  const isNilSeg = (from: number, to: number): boolean => token.slice(from, to).trim() === "nil";
+  let depth = 0;
+  let inQuote = false;
+  let segStart = 0;
+  for (let i = 0; i < token.length; i++) {
+    const c = token[i];
+    if (inQuote) {
+      if (c === '"') inQuote = false;
+      continue;
+    }
+    if (c === '"') inQuote = true;
+    else if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0 && c === "|") {
+      if (isNilSeg(segStart, i)) return true;
+      segStart = i + 1;
+    }
+  }
+  return isNilSeg(segStart, token.length);
+}
+
 /** A bare lowercase identifier — the shape druid uses for an optional `@return` name. */
 const RETURN_NAME = /^[a-z_][A-Za-z0-9_]*$/;
 
@@ -112,7 +311,9 @@ function parseParam(rest: string): LibraryParam {
   const isOptional = !isVararg && rawName.endsWith("?");
   const name = isOptional ? rawName.slice(0, -1) : rawName;
   const { type, rest: doc } = readTypeToken(afterName);
-  return { name, types: type ? [type] : [], doc, isOptional, isVararg };
+  const param: LibraryParam = { name, types: type ? [type] : [], doc, isOptional, isVararg };
+  if (type && hasTopLevelNil(type)) param.isNilable = true;
+  return param;
 }
 
 function parseReturn(rest: string): LibraryParam {
@@ -152,9 +353,12 @@ function parseField(rest: string): LibraryField {
   const spaceAt = body.search(/\s/);
   const rawName = spaceAt === -1 ? body : body.slice(0, spaceAt);
   const afterName = spaceAt === -1 ? "" : body.slice(spaceAt).trim();
-  const isOptional = rawName.endsWith("?");
-  const name = isOptional ? rawName.slice(0, -1) : rawName;
+  const nameSuffix = rawName.endsWith("?");
+  const name = nameSuffix ? rawName.slice(0, -1) : rawName;
   const { type, rest: doc } = readTypeToken(afterName);
+  // Interface properties carry no optional-before-required rule, so a `|nil`/`?` type
+  // folds straight into the field's optionality.
+  const isOptional = nameSuffix || (type !== "" && hasTopLevelNil(type));
   return {
     name,
     types: type ? [type] : [],
@@ -166,7 +370,15 @@ function parseField(rest: string): LibraryField {
 
 function parseVararg(rest: string): LibraryParam {
   const { type, rest: doc } = readTypeToken(rest);
-  return { name: "...", types: type ? [type] : [], doc, isOptional: false, isVararg: true };
+  const param: LibraryParam = {
+    name: "...",
+    types: type ? [type] : [],
+    doc,
+    isOptional: false,
+    isVararg: true,
+  };
+  if (type && hasTopLevelNil(type)) param.isNilable = true;
+  return param;
 }
 
 function parseGenerics(rest: string): LibraryGeneric[] {
@@ -181,12 +393,50 @@ function parseGenerics(rest: string): LibraryGeneric[] {
     });
 }
 
-/** Parse a `@class Name[ : parent]` head. The parent is kept as a single raw token. */
+/**
+ * Read one class-head token from `s` starting at `start`, tracking `<[({` depth so a
+ * generic like `Bar<A, B>` stays whole. Ends at the first top-level space/tab, `:`, or
+ * `,` (none consumed). Returns the trimmed token and its end index. Distinct from
+ * `readTypeToken`, whose `fun(...)` `:`/`,` continuation rule wrongly glues a
+ * `Name: Parent` head together.
+ */
+function readClassToken(s: string, start: number): { token: string; end: number } {
+  let depth = 0;
+  let i = start;
+  for (; i < s.length; i++) {
+    const c = s[i];
+    if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
+    else if (depth === 0 && (c === " " || c === "\t" || c === ":" || c === ",")) break;
+  }
+  return { token: s.slice(start, i).trim(), end: i };
+}
+
+/**
+ * Parse a `@class Name[: parent[, parent...]] [description]` head. The identifier and
+ * optional parent list are read as bracket-aware tokens; any trailing human
+ * description is dropped. Multiple parents are joined with `", "` to match the single
+ * `extends` string the emitter renders.
+ */
 function parseClassHead(rest: string): { name: string; extends?: string } {
-  const colon = rest.indexOf(":");
-  if (colon === -1) return { name: rest.trim() };
-  const parent = rest.slice(colon + 1).trim();
-  return { name: rest.slice(0, colon).trim(), ...(parent ? { extends: parent } : {}) };
+  const s = rest.trim();
+  const { token: name, end: afterName } = readClassToken(s, 0);
+  let i = afterName;
+  while (i < s.length && (s[i] === " " || s[i] === "\t")) i++;
+  if (s[i] !== ":") return { name };
+  i++;
+  const parents: string[] = [];
+  while (true) {
+    while (i < s.length && (s[i] === " " || s[i] === "\t")) i++;
+    const { token, end } = readClassToken(s, i);
+    if (token !== "") parents.push(token);
+    i = end;
+    while (i < s.length && (s[i] === " " || s[i] === "\t")) i++;
+    if (s[i] !== ",") break;
+    i++;
+  }
+  const extendsStr = parents.join(", ");
+  return { name, ...(extendsStr ? { extends: extendsStr } : {}) };
 }
 
 interface FunctionDecl {
@@ -260,6 +510,19 @@ export function parseLualsSource(source: string): LibraryModel {
   let pending = emptyPending();
   let openClass: LibraryInterface | null = null;
   let lastOpenedClass: string | null = null;
+  let moduleObject: string | undefined;
+  let lastModuleFunction: LibraryMethod | null = null;
+  // The one open function-local `---@class` block (squid's `SquidInstance` inside
+  // `Squid.new`). `owner` is the function whose body it sits in, so a returned local
+  // bound to it infers the function's return; `pendingType` is a `---@type fun(...)`
+  // armed for the next member key.
+  let localClass: {
+    iface: LibraryInterface;
+    localVar: string | null;
+    owner: LibraryMethod | null;
+    pendingType: string | null;
+    returnedSelf: boolean;
+  } | null = null;
 
   const ensureInterface = (name: string): LibraryInterface => {
     const existing = byName.get(name);
@@ -282,11 +545,93 @@ export function parseLualsSource(source: string): LibraryModel {
     generics: pending.generics,
     params: pending.params,
     returns: pending.returns,
+    ...(pending.visibility ? { visibility: pending.visibility } : {}),
   });
 
+  // Interpret one indented line while a function-local `---@class` block is open. Only
+  // the `---@type fun(...)` + next `<key> = ...` member pattern, the backing `local`,
+  // and the `return <local>` are recognized; every other indented line stays opaque.
+  const handleLocalClassLine = (line: string): void => {
+    const lc = localClass;
+    if (!lc) return;
+    const typeMatch = /^---@type\s+(.+)$/.exec(line);
+    if (typeMatch) {
+      const { type } = readTypeToken(typeMatch[1] ?? "");
+      // A non-`fun` `---@type` also disarms a previously-armed one.
+      lc.pendingType = /^fun\s*\(/.test(type) ? type : null;
+      return;
+    }
+    if (lc.pendingType) {
+      const keyMatch = /^([A-Za-z_]\w*)\s*=/.exec(line);
+      if (keyMatch) {
+        const { params, returns } = funToMethodParts(lc.pendingType);
+        lc.iface.methods.push({
+          name: keyMatch[1] as string,
+          brief: "",
+          generics: [],
+          params,
+          returns,
+        });
+        lc.pendingType = null;
+        return;
+      }
+      // Not the immediately-following member key: the armed type has no member.
+      lc.pendingType = null;
+    }
+    const returnMatch = /^return\s+([A-Za-z_]\w*)\s*$/.exec(line);
+    if (returnMatch) {
+      if (returnMatch[1] === lc.localVar) lc.returnedSelf = true;
+      return;
+    }
+    const local = LOCAL_ASSIGN.exec(line);
+    if (local) {
+      // A `---@class` annotates the immediately-following declaration, so only the
+      // first local after the class opens is the instance; a later local must not rebind.
+      if (lc.localVar === null) lc.localVar = local[1] ?? null;
+      return;
+    }
+  };
+
   for (const raw of source.split("\n")) {
-    // Column-0 discipline: a line with leading whitespace is opaque to the scanner.
-    if (/^\s/.test(raw) || raw.length === 0) continue;
+    const indented = /^\s/.test(raw);
+    if (indented || raw.length === 0) {
+      if (localClass) {
+        handleLocalClassLine(raw.trim());
+      } else if (indented) {
+        // Only an indented `---@class` opens function-local capture; every other
+        // indented line (druid-style `---@cast`/`---@type` narrowing) stays opaque.
+        const classMatch = /^---@class\s+(.+)$/.exec(raw.trim());
+        if (classMatch) {
+          const head = parseClassHead(classMatch[1] ?? "");
+          const iface = ensureInterface(head.name);
+          if (head.extends) iface.extends = head.extends;
+          localClass = {
+            iface,
+            localVar: null,
+            owner: lastModuleFunction,
+            pendingType: null,
+            returnedSelf: false,
+          };
+        }
+      }
+      continue;
+    }
+
+    // A column-0 line ends any open function-local class (dedent). Apply the inferred
+    // return to the owner only when it declared no explicit `---@return`.
+    if (localClass) {
+      const lc = localClass;
+      if (lc.returnedSelf && lc.owner && lc.owner.returns.length === 0) {
+        lc.owner.returns.push({
+          name: "",
+          types: [lc.iface.name],
+          doc: "",
+          isOptional: false,
+          isVararg: false,
+        });
+      }
+      localClass = null;
+    }
 
     if (raw.startsWith("---@")) {
       const tagMatch = /^---@([a-zA-Z]+)\s*(.*)$/.exec(raw);
@@ -300,6 +645,7 @@ export function parseLualsSource(source: string): LibraryModel {
           if (head.extends) iface.extends = head.extends;
           if (pending.doc.length > 0 && iface.brief === "") iface.brief = pending.doc.join("\n");
           if (pending.generics.length > 0) iface.generics = pending.generics;
+          if (pending.overloads.length > 0) iface.overloads = pending.overloads;
           openClass = iface;
           lastOpenedClass = head.name;
           pending = emptyPending();
@@ -325,6 +671,15 @@ export function parseLualsSource(source: string): LibraryModel {
           pending.generics.push(...parseGenerics(rest));
           break;
         }
+        case "overload": {
+          // A class-level `---@overload fun(...)`: keep the raw `fun(...)` token via
+          // readTypeToken (its spaced `): ret` return stays whole) plus the trailing
+          // doc, and transfer to the interface on the following `@class` — like brief
+          // and generics. A non-`fun` overload is outside the modeled subset and dropped.
+          const { type, rest: doc } = readTypeToken(rest);
+          if (/^fun\s*\(/.test(type)) pending.overloads.push({ type, doc });
+          break;
+        }
         case "alias": {
           const spaceAt = rest.search(/\s/);
           const name = spaceAt === -1 ? rest : rest.slice(0, spaceAt);
@@ -333,9 +688,19 @@ export function parseLualsSource(source: string): LibraryModel {
           pending = emptyPending();
           break;
         }
+        case "private":
+        case "protected":
+        case "package":
+        case "local": {
+          // A standalone visibility tag on the pending block marks the next function
+          // declaration's method/module-function `visibility` (a `@class` or `@alias`
+          // that consumes the block first resets it, so it never leaks onto a type).
+          pending.visibility = tag as LibraryMethodVisibility;
+          break;
+        }
         default:
-          // @private, @protected, @cast, @type, @diagnostic, @overload, ... — outside
-          // the Druid subset; recognized as a tag and skipped, never treated as doc.
+          // @cast, @type, @diagnostic, ... — outside the Druid subset; recognized as a
+          // tag and skipped, never treated as doc.
           break;
       }
       continue;
@@ -348,12 +713,16 @@ export function parseLualsSource(source: string): LibraryModel {
 
     const decl = parseFunctionDecl(raw);
     if (decl) {
+      const method = methodFromPending(decl.name);
       if (decl.kind === "method") {
         const target = decl.receiver ? (receiverBinding.get(decl.receiver) ?? decl.receiver) : "";
-        ensureInterface(target).methods.push(methodFromPending(decl.name));
+        ensureInterface(target).methods.push(method);
       } else if (decl.qualified) {
-        moduleFunctions.push(methodFromPending(decl.name));
+        moduleFunctions.push(method);
       }
+      // Any function may host a function-local `---@class`; remember the enclosing
+      // function so a returned local can infer its return, even a bare helper.
+      lastModuleFunction = method;
       pending = emptyPending();
       openClass = null;
       continue;
@@ -366,10 +735,34 @@ export function parseLualsSource(source: string): LibraryModel {
       lastOpenedClass = null;
       openClass = null;
       pending = emptyPending();
+      continue;
+    }
+
+    // A column-0 `return <name>` handing back a local bound to an opened `---@class`
+    // marks that class as the module object (its fields become module-level consts).
+    // Restricted to squid's constants-table idiom to keep every other library's golden
+    // untouched: the returned local is named after its class (`local Squid = {}` /
+    // `return Squid`, not a generic `local M` alias), the class carries at least one
+    // public field, and it has no methods. A component/instance class (colon methods),
+    // an opaque handle (no fields), or an `M`-aliased module table is a type consumers
+    // reference or a plain namespace, so it stays a standalone interface.
+    const returnStmt = /^return\s+([A-Za-z_][\w.]*)\s*$/.exec(raw);
+    if (returnStmt) {
+      const name = returnStmt[1] as string;
+      const resolvedName = receiverBinding.get(name) ?? (byName.has(name) ? name : undefined);
+      const resolved = resolvedName ? byName.get(resolvedName) : undefined;
+      if (
+        resolved &&
+        resolvedName === name &&
+        resolved.methods.length === 0 &&
+        resolved.fields.some((f) => f.visibility === undefined || f.visibility === "public")
+      ) {
+        moduleObject = resolved.name;
+      }
     }
   }
 
-  return { interfaces, aliases, moduleFunctions };
+  return { interfaces, aliases, moduleFunctions, ...(moduleObject ? { moduleObject } : {}) };
 }
 
 /**
@@ -383,8 +776,10 @@ export function mergeLibraryModels(models: LibraryModel[]): LibraryModel {
   const byName = new Map<string, LibraryInterface>();
   const aliases: LibraryAlias[] = [];
   const moduleFunctions: LibraryMethod[] = [];
+  let moduleObject: string | undefined;
 
   for (const model of models) {
+    if (!moduleObject && model.moduleObject) moduleObject = model.moduleObject;
     for (const iface of model.interfaces) {
       const existing = byName.get(iface.name);
       if (!existing) {
@@ -395,6 +790,9 @@ export function mergeLibraryModels(models: LibraryModel[]): LibraryModel {
           fields: [...iface.fields],
           methods: [...iface.methods],
           brief: iface.brief,
+          ...(iface.overloads && iface.overloads.length > 0
+            ? { overloads: [...iface.overloads] }
+            : {}),
         };
         byName.set(iface.name, copy);
         interfaces.push(copy);
@@ -407,6 +805,13 @@ export function mergeLibraryModels(models: LibraryModel[]): LibraryModel {
       if (existing.generics.length === 0 && iface.generics.length > 0) {
         existing.generics = [...iface.generics];
       }
+      if (
+        (!existing.overloads || existing.overloads.length === 0) &&
+        iface.overloads &&
+        iface.overloads.length > 0
+      ) {
+        existing.overloads = [...iface.overloads];
+      }
     }
     aliases.push(...model.aliases);
     moduleFunctions.push(...model.moduleFunctions);
@@ -419,7 +824,7 @@ export function mergeLibraryModels(models: LibraryModel[]): LibraryModel {
   // overloaded module functions keep every signature.
   for (const iface of interfaces) iface.fields = dedupeByName(iface.fields);
 
-  return { interfaces, aliases, moduleFunctions };
+  return { interfaces, aliases, moduleFunctions, ...(moduleObject ? { moduleObject } : {}) };
 }
 
 function dedupeByName<T extends { name: string }>(items: T[]): T[] {

package/scripts/sync-luals-types.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { type AnnotationOverrides, applyAnnotationOverrides } from "./apply-luals-overrides";
 import { emitLibraryDeclarations } from "./emit-library-dts";
 import { lowerLibraryModel } from "./lower-api-doc";
 import { buildFidelityReport, type FidelityReport } from "./luals-fidelity";
@@ -22,6 +23,10 @@ export interface LualsTarget {
   // SPDX-style license id, surfaced by the docs-site provenance block. Optional
   // in the config; the docs-site defaults an absent value to "".
   license?: string;
+  // Post-merge corrections applied in `buildTargetModel` for the cases where an
+  // upstream annotation the fixtures freeze diverges from the runtime. Optional and
+  // loud-failing on an absent key — see `apply-luals-overrides.ts`.
+  annotationOverrides?: AnnotationOverrides;
 }
 
 export interface LualsTargets {
@@ -57,6 +62,9 @@ export function readLualsTargets(packageRoot: string): LualsTarget[] {
       typeRenames: entry.typeRenames ?? {},
       ignore: entry.ignore ?? [],
       ...(entry.license !== undefined ? { license: entry.license } : {}),
+      ...(entry.annotationOverrides !== undefined
+        ? { annotationOverrides: entry.annotationOverrides }
+        : {}),
     };
   });
 }
@@ -188,7 +196,13 @@ export function buildTargetModel(
   const parsed = new Map<string, LibraryModel>();
   for (const rel of files) parsed.set(rel, parseLualsSource(readFileSync(join(root, rel), "utf8")));
   const merged = mergeLibraryModels([...parsed.values()]);
-  return { ...merged, moduleFunctions: parsed.get(ownFile)?.moduleFunctions ?? [] };
+  const model: LibraryModel = {
+    ...merged,
+    moduleFunctions: parsed.get(ownFile)?.moduleFunctions ?? [],
+  };
+  return target.annotationOverrides
+    ? applyAnnotationOverrides(model, target.annotationOverrides)
+    : model;
 }
 
 export function buildTargetFidelity(packageRoot: string, target: LualsTarget): FidelityReport {