@defold-typescript/library-types 0.20.8 → 0.21.1

package/scripts/emit-library-dts.ts

@@ -0,0 +1,252 @@
+/**
+ * Renders a `LibraryModel` (from `parse-luals.ts`) into a committed `.d.ts`: a
+ * single `declare module '<moduleId>' { ... }` block of plain `interface`s, `type`
+ * aliases, and `export function`s, mapping every member type through the shipped
+ * `mapLualsType`. Pure and deterministic — output depends only on the model and the
+ * options — so the `--emit` CLI arm and its golden round-trip test agree
+ * byte-for-byte.
+ *
+ * A sibling to `@defold-typescript/types`' `emit-dts.ts`, not an extension of it:
+ * that emitter is `ApiModule`-shaped and Defold-specific, whereas `LibraryModel` is
+ * a different OOP shape. Only `renderDocComment`, `TS_RESERVED_NAMES`, and
+ * `TS_IDENTIFIER` are reused from the types surface.
+ *
+ * Renders interface/method generic parameters and `extends` clauses: each generic
+ * `name` is scoped into a child `MapContext` (an identity rename) so a bare `T`
+ * resolves to `T` instead of lowering to `unknown`, constraints and `extends`
+ * targets map through the existing rename map, and an `extends` clause is emitted
+ * only for parents that resolve to a declared interface.
+ */
+
+import {
+  luaMultiReturn,
+  renderDocComment,
+  TS_IDENTIFIER,
+  TS_RESERVED_NAMES,
+  varargElementType,
+} from "@defold-typescript/types";
+import {
+  type MapContext,
+  mapLualsType,
+  matchSelfHookField,
+  scopeGenerics,
+} from "./map-luals-types";
+import type {
+  LibraryAlias,
+  LibraryGeneric,
+  LibraryInterface,
+  LibraryMethod,
+  LibraryModel,
+  LibraryParam,
+} from "./parse-luals";
+
+export interface EmitLibraryOptions {
+  moduleId: string;
+  typeRenames?: Record<string, string>;
+}
+
+const INDENT = "\t";
+
+/** A model type name (dotted like `druid.button`) reduced to a legal TS identifier. */
+export function sanitizeTypeName(name: string): string {
+  const cleaned = name.replace(/[^A-Za-z0-9_$]/g, "_");
+  return /^[A-Za-z_$]/.test(cleaned) ? cleaned : `_${cleaned}`;
+}
+
+/**
+ * An interface/type member key: bare when it is a plain identifier that is not a
+ * reserved word, otherwise a quoted string literal so a name like `default` or
+ * `new` stays an ordinary member instead of becoming a syntax error (or, for
+ * `new`, a construct signature).
+ */
+function memberKey(name: string): string {
+  return TS_IDENTIFIER.test(name) && !TS_RESERVED_NAMES.has(name) ? name : JSON.stringify(name);
+}
+
+/** A parameter name coerced to a legal, non-reserved binding form. */
+function safeParamName(name: string, index: number): string {
+  if (!TS_IDENTIFIER.test(name)) return `arg${index}`;
+  return TS_RESERVED_NAMES.has(name) ? `${name}_` : name;
+}
+
+export function mapTypes(types: readonly string[], ctx: MapContext): string {
+  if (types.length === 0) return "unknown";
+  return types.map((token) => mapLualsType(token, ctx).ts).join(" | ");
+}
+
+/** A generic parameter list `<A extends C, B>`, or `""` when there are none. */
+export function renderGenericParams(generics: readonly LibraryGeneric[], ctx: MapContext): string {
+  if (generics.length === 0) return "";
+  const params = generics.map((generic) => {
+    if (generic.constraint === undefined || generic.constraint === "") return generic.name;
+    const mapped = mapTypes([generic.constraint], ctx);
+    // An undeclared constraint lowers to `unknown`; drop it (mirror `renderExtends`'s
+    // declared-only filter) rather than emit a vacuous `<T extends unknown>`.
+    return mapped === "unknown" ? generic.name : `${generic.name} extends ${mapped}`;
+  });
+  return `<${params.join(", ")}>`;
+}
+
+/** The TS return type for a self-hook field lowered to an optional method. */
+function renderHookReturn(returnTokens: readonly string[], ctx: MapContext): string {
+  if (returnTokens.length === 0) return "void";
+  if (returnTokens.length === 1) return mapTypes([returnTokens[0] as string], ctx);
+  return luaMultiReturn(returnTokens.map((token) => mapTypes([token], ctx)));
+}
+
+/**
+ * An ` extends X, Y` clause built from `iface.extends` split on commas, keeping only
+ * parents that name a declared interface (so no `extends unknown` is ever emitted),
+ * mapped through the rename map; `""` when none survive.
+ */
+function renderExtends(
+  iface: LibraryInterface,
+  ctx: MapContext,
+  interfaceNames: ReadonlySet<string>,
+): string {
+  if (!iface.extends) return "";
+  const parents = iface.extends
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => interfaceNames.has(name))
+    .map((name) => mapTypes([name], ctx));
+  return parents.length > 0 ? ` extends ${parents.join(", ")}` : "";
+}
+
+function renderParams(params: readonly LibraryParam[], ctx: MapContext): string {
+  return params
+    .map((param, index) => {
+      const mapped = mapTypes(param.types, ctx);
+      if (param.isVararg) {
+        return `...args: ${varargElementType(mapped)}`;
+      }
+      const optional = param.isOptional ? "?" : "";
+      return `${safeParamName(param.name, index)}${optional}: ${mapped}`;
+    })
+    .join(", ");
+}
+
+function renderReturn(returns: readonly LibraryParam[], ctx: MapContext): string {
+  if (returns.length === 0) return "void";
+  if (returns.length === 1) return mapTypes((returns[0] as LibraryParam).types, ctx);
+  return luaMultiReturn(returns.map((ret) => mapTypes(ret.types, ctx)));
+}
+
+function pushDoc(lines: string[], summary: string, indent: string): void {
+  for (const line of renderDocComment({ summary })) lines.push(`${indent}${line}`);
+}
+
+function renderAlias(alias: LibraryAlias, ctx: MapContext): string[] {
+  const lines: string[] = [];
+  pushDoc(lines, alias.doc, INDENT);
+  lines.push(`${INDENT}type ${sanitizeTypeName(alias.name)} = ${mapTypes(alias.types, ctx)};`);
+  return lines;
+}
+
+function renderInterface(
+  iface: LibraryInterface,
+  ctx: MapContext,
+  interfaceNames: ReadonlySet<string>,
+): string[] {
+  const lines: string[] = [];
+  pushDoc(lines, iface.brief, INDENT);
+  const ifaceCtx = scopeGenerics(ctx, iface.generics);
+  const params = renderGenericParams(iface.generics, ifaceCtx);
+  const extendsClause = renderExtends(iface, ifaceCtx, interfaceNames);
+  lines.push(`${INDENT}interface ${sanitizeTypeName(iface.name)}${params}${extendsClause} {`);
+  const body = INDENT + INDENT;
+  for (const field of iface.fields) {
+    // A base's self-receiving lifecycle hook is emitted as a permissive optional
+    // method (`name?(...args: any[]): ret`) so a concrete subinterface's refined
+    // override stays assignable under `extends`; strict function-field variance
+    // would reject it.
+    const hookReturns = matchSelfHookField(field.types, iface.name);
+    if (hookReturns !== null) {
+      pushDoc(lines, field.doc, body);
+      lines.push(
+        `${body}${memberKey(field.name)}?(...args: any[]): ${renderHookReturn(hookReturns, ifaceCtx)};`,
+      );
+      continue;
+    }
+    const optional = field.isOptional ? "?" : "";
+    lines.push(`${body}${memberKey(field.name)}${optional}: ${mapTypes(field.types, ifaceCtx)};`);
+  }
+  for (const method of iface.methods) {
+    pushDoc(lines, method.brief, body);
+    const methodCtx = scopeGenerics(ifaceCtx, method.generics);
+    const methodParams = renderGenericParams(method.generics, methodCtx);
+    lines.push(
+      `${body}${memberKey(method.name)}${methodParams}(${renderParams(
+        method.params,
+        methodCtx,
+      )}): ${renderReturn(method.returns, methodCtx)};`,
+    );
+  }
+  lines.push(`${INDENT}}`);
+  return lines;
+}
+
+function renderModuleFunction(fn: LibraryMethod, ctx: MapContext): string[] {
+  const lines: string[] = [];
+  pushDoc(lines, fn.brief, INDENT);
+  const fnCtx = scopeGenerics(ctx, fn.generics);
+  const genericParams = renderGenericParams(fn.generics, fnCtx);
+  const params = renderParams(fn.params, fnCtx);
+  const signature = `${genericParams}(${params ? `this: void, ${params}` : "this: void"}): ${renderReturn(
+    fn.returns,
+    fnCtx,
+  )}`;
+  const isReserved = TS_RESERVED_NAMES.has(fn.name) || !TS_IDENTIFIER.test(fn.name);
+  if (isReserved) {
+    // A reserved call name (`new`, `delete`) is illegal as a `function` identifier,
+    // so it is declared under an internal alias and re-exported under its real name.
+    const internal = `${sanitizeTypeName(fn.name)}_`;
+    lines.push(`${INDENT}export function ${internal}${signature};`);
+    lines.push(`${INDENT}export { ${internal} as ${fn.name} };`);
+  } else {
+    lines.push(`${INDENT}export function ${fn.name}${signature};`);
+  }
+  return lines;
+}
+
+/**
+ * The `MapContext` a library model maps every type token through: each interface
+ * and alias name is a known reference plus a sanitized rename (dotted `druid.button`
+ * -> `druid_button`), layered over the caller's `typeRenames`. Shared by the emitter
+ * (declaration text) and the api-doc lowering so both resolve model references
+ * identically — the invariant that keeps `api-doc/<ns>.json` byte-equivalent to
+ * `generated/<ns>.d.ts`.
+ */
+export function buildModelContext(
+  model: LibraryModel,
+  typeRenames?: Record<string, string>,
+): MapContext {
+  const declaredNames = [
+    ...model.interfaces.map((iface) => iface.name),
+    ...model.aliases.map((alias) => alias.name),
+  ];
+  const nameRenames: Record<string, string> = {};
+  for (const name of declaredNames) nameRenames[name] = sanitizeTypeName(name);
+  return {
+    knownNames: new Set(declaredNames),
+    typeRenames: { ...(typeRenames ?? {}), ...nameRenames },
+  };
+}
+
+/**
+ * Emit the `.d.ts` text for one library model. References to the model's own
+ * interfaces and aliases resolve to their sanitized declaration names via a rename
+ * map layered over the caller's `typeRenames`; unresolved references lower to
+ * `unknown` inside `mapLualsType` exactly as the fidelity report records them.
+ */
+export function emitLibraryDeclarations(model: LibraryModel, opts: EmitLibraryOptions): string {
+  const ctx = buildModelContext(model, opts.typeRenames);
+
+  const interfaceNames = new Set(model.interfaces.map((iface) => iface.name));
+  const out: string[] = ["/** @noResolution */", `declare module '${opts.moduleId}' {`];
+  for (const alias of model.aliases) out.push(...renderAlias(alias, ctx));
+  for (const iface of model.interfaces) out.push(...renderInterface(iface, ctx, interfaceNames));
+  for (const fn of model.moduleFunctions) out.push(...renderModuleFunction(fn, ctx));
+  out.push("}");
+  return `${out.join("\n")}\n`;
+}

package/scripts/lower-api-doc.ts

@@ -0,0 +1,115 @@
+/**
+ * Lower a LuaLS `LibraryModel` (`parse-luals.ts`) to the `{ info, elements }`
+ * ref-doc JSON shape that `@defold-typescript/types`' `parseDefoldApiDoc`
+ * accepts, so the docs-site renders a LuaLS-sourced library through the exact
+ * `/api` path a ts-defold `.d.ts` takes. Mirrors `extract-api-doc.ts`: pure and
+ * node-free (model in, object out) so it is unit-testable and reused by the
+ * `--api-doc` orchestrator arm.
+ *
+ * We lower from the model rather than re-running `extractApiDoc` on the emitted
+ * `generated/<ns>.d.ts`: a druid-style library's surface is almost entirely
+ * `interface` declarations, and `extractApiDoc` only emits interfaces reachable
+ * from an emitted function/variable or an `export =`, so the emitted `.d.ts`
+ * yields near-empty elements. The model carries the interfaces explicitly.
+ */
+
+import {
+  buildModelContext,
+  mapTypes,
+  renderGenericParams,
+  sanitizeTypeName,
+} from "./emit-library-dts";
+import { type MapContext, scopeGenerics } from "./map-luals-types";
+import type { LibraryField, LibraryMethod, LibraryModel, LibraryParam } from "./parse-luals";
+
+// A field with an explicit non-public visibility is internal surface; keep only
+// fields with no visibility or an explicit `public`, mirroring how LuaLS hides
+// `private`/`protected`/`package` members from a class's public shape.
+function isPublicField(field: LibraryField): boolean {
+  return field.visibility === undefined || field.visibility === "public";
+}
+
+// Each type token is mapped independently (one mapped TS string per token) so the
+// ref-doc `types` array stays token-per-slot the way engine ref-docs are shaped.
+function mapTokens(tokens: readonly string[], ctx: MapContext): string[] {
+  return tokens.map((token) => mapTypes([token], ctx));
+}
+
+function parameterElement(param: LibraryParam, ctx: MapContext): Record<string, unknown> {
+  // A vararg's element type stays a plain mapped token here; the renderer arrayifies
+  // it (`...args: T[]`) from the `is_vararg` flag, keeping the JSON structurally honest.
+  return {
+    name: param.isVararg ? "...args" : param.name,
+    doc: param.doc,
+    types: mapTokens(param.types, ctx),
+    is_optional: param.isOptional ? "True" : "False",
+    is_vararg: param.isVararg ? "True" : "False",
+  };
+}
+
+function returnElement(ret: LibraryParam, ctx: MapContext): Record<string, unknown> {
+  return { name: "", doc: ret.doc, types: mapTokens(ret.types, ctx) };
+}
+
+function functionElement(method: LibraryMethod, ctx: MapContext): Record<string, unknown> {
+  const fnCtx = scopeGenerics(ctx, method.generics);
+  const generics = renderGenericParams(method.generics, fnCtx);
+  return {
+    type: "FUNCTION",
+    name: method.name,
+    brief: method.brief,
+    description: method.brief,
+    ...(generics !== "" ? { generics } : {}),
+    parameters: method.params.map((param) => parameterElement(param, fnCtx)),
+    returnvalues: method.returns.map((ret) => returnElement(ret, fnCtx)),
+  };
+}
+
+function propertyElement(field: LibraryField, ctx: MapContext): Record<string, unknown> {
+  return {
+    name: field.name,
+    brief: field.doc,
+    description: field.doc,
+    types: mapTokens(field.types, ctx),
+  };
+}
+
+export function lowerLibraryModel(
+  model: LibraryModel,
+  { namespace, typeRenames }: { namespace: string; typeRenames?: Record<string, string> },
+): unknown {
+  const ctx = buildModelContext(model, typeRenames);
+  const elements: Record<string, unknown>[] = [];
+
+  for (const fn of model.moduleFunctions) {
+    elements.push(functionElement(fn, ctx));
+  }
+
+  for (const iface of model.interfaces) {
+    const ifaceCtx = scopeGenerics(ctx, iface.generics);
+    const functions = iface.methods.map((method) => functionElement(method, ifaceCtx));
+    const properties = iface.fields
+      .filter(isPublicField)
+      .map((field) => propertyElement(field, ifaceCtx));
+    elements.push({
+      type: "TYPEDEF",
+      name: sanitizeTypeName(iface.name),
+      ...(functions.length > 0 ? { functions } : {}),
+      ...(properties.length > 0 ? { properties } : {}),
+    });
+  }
+
+  for (const alias of model.aliases) {
+    elements.push({ type: "TYPEDEF", name: sanitizeTypeName(alias.name) });
+  }
+
+  // The module's own `@class` (named for the namespace, e.g. `@class druid`)
+  // carries the library's summary; use it as the page description so a
+  // LuaLS-sourced library reads with an intro like every other `/api` page,
+  // rather than opening on a bare provenance block. `brief` is its first line.
+  const moduleClass = model.interfaces.find((iface) => iface.name === namespace);
+  const description = moduleClass?.brief ?? "";
+  const brief = description.split("\n")[0] ?? "";
+
+  return { info: { namespace, brief, description }, elements };
+}

package/scripts/luals-fidelity.ts

@@ -10,8 +10,8 @@
  * sorted-unique token list so the gap is visible instead of silent.
  */
 
-import { type MapContext, mapLualsType } from "./map-luals-types";
-import type { LibraryModel } from "./parse-luals";
+import { type MapContext, mapLualsType, scopeGenerics } from "./map-luals-types";
+import type { LibraryGeneric, LibraryModel } from "./parse-luals";
 
 export interface FidelityReport {
   namespace: string;
@@ -51,10 +51,10 @@ export function buildFidelityReport(
   let undocumentedMembers = 0;
   const unknownTokens = new Set<string>();
 
-  const mapTokens = (tokens: string[]): void => {
+  const mapTokens = (tokens: string[], mapCtx: MapContext): void => {
     for (const token of tokens) {
       totalTypeTokens++;
-      const { unknowns } = mapLualsType(token, ctx);
+      const { unknowns } = mapLualsType(token, mapCtx);
       unknownFallbacks += unknowns.length;
       for (const u of unknowns) unknownTokens.add(u);
     }
@@ -62,28 +62,49 @@ export function buildFidelityReport(
 
   const undocumented = (doc: string): boolean => doc.trim() === "";
 
+  const mapConstraints = (generics: readonly LibraryGeneric[], mapCtx: MapContext): void => {
+    for (const generic of generics) {
+      if (generic.constraint) mapTokens([generic.constraint], mapCtx);
+    }
+  };
+
   for (const iface of model.interfaces) {
+    const ifaceCtx = scopeGenerics(ctx, iface.generics);
+    if (iface.extends) {
+      mapTokens(
+        iface.extends
+          .split(",")
+          .map((parent) => parent.trim())
+          .filter((parent) => parent !== ""),
+        ifaceCtx,
+      );
+    }
+    mapConstraints(iface.generics, ifaceCtx);
     for (const field of iface.fields) {
       totalMembers++;
       if (undocumented(field.doc)) undocumentedMembers++;
-      mapTokens(field.types);
+      mapTokens(field.types, ifaceCtx);
     }
     for (const method of iface.methods) {
       totalMembers++;
       if (undocumented(method.brief)) undocumentedMembers++;
-      for (const param of method.params) mapTokens(param.types);
-      for (const ret of method.returns) mapTokens(ret.types);
+      const methodCtx = scopeGenerics(ifaceCtx, method.generics);
+      mapConstraints(method.generics, methodCtx);
+      for (const param of method.params) mapTokens(param.types, methodCtx);
+      for (const ret of method.returns) mapTokens(ret.types, methodCtx);
     }
   }
 
   for (const fn of model.moduleFunctions) {
     totalMembers++;
     if (undocumented(fn.brief)) undocumentedMembers++;
-    for (const param of fn.params) mapTokens(param.types);
-    for (const ret of fn.returns) mapTokens(ret.types);
+    const fnCtx = scopeGenerics(ctx, fn.generics);
+    mapConstraints(fn.generics, fnCtx);
+    for (const param of fn.params) mapTokens(param.types, fnCtx);
+    for (const ret of fn.returns) mapTokens(ret.types, fnCtx);
   }
 
-  for (const alias of model.aliases) mapTokens(alias.types);
+  for (const alias of model.aliases) mapTokens(alias.types, ctx);
 
   const coverage =
     totalTypeTokens === 0

package/scripts/map-luals-types.ts

@@ -25,6 +25,24 @@ export interface MapResult {
   unknowns: string[];
 }
 
+/**
+ * A child `MapContext` with each generic parameter `name` added as an identity
+ * rename and a known name, so a bare `T` maps to `T` instead of lowering to
+ * `unknown`. Returns the same ctx when there are no generics. Shared by the emitter
+ * (declaration text) and the fidelity report (coverage) so both scope generics
+ * identically.
+ */
+export function scopeGenerics(ctx: MapContext, generics: readonly { name: string }[]): MapContext {
+  if (generics.length === 0) return ctx;
+  const knownNames = new Set(ctx.knownNames);
+  const typeRenames = { ...ctx.typeRenames };
+  for (const generic of generics) {
+    knownNames.add(generic.name);
+    typeRenames[generic.name] = generic.name;
+  }
+  return { knownNames, typeRenames };
+}
+
 const SCALARS: Readonly<Record<string, string>> = {
   integer: "number",
   number: "number",
@@ -256,3 +274,50 @@ export function mapLualsType(token: string, ctx: MapContext): MapResult {
   const ts = mapToken(token, ctx, unknowns);
   return { ts, unknowns };
 }
+
+/**
+ * When `types` is exactly one `fun(self: <selfTypeName>, ...)` token — optionally
+ * unioned with `nil` — whose first parameter is `self` typed as the enclosing
+ * interface's own model name, return the function's raw return tokens (an empty
+ * array for a `void`/no-return hook). Returns `null` for every other shape: a data
+ * field, a non-`fun` type, an untyped `self`, or a `self` typed as a *different*
+ * interface. Reuses the same bracket-aware split/match as the mapper so nested
+ * commas and colons inside a param type never mis-split.
+ *
+ * The `fun` is isolated through its params `)` before the return is read, so a
+ * return union or nullable return (which also sits at bracket depth 0, after the
+ * `)`) survives instead of being mis-split as an outer `|nil` — the same
+ * ordering rule as the mapper's `fun(...)` return-union handling.
+ */
+export function matchSelfHookField(
+  types: readonly string[],
+  selfTypeName: string,
+): string[] | null {
+  if (types.length !== 1) return null;
+  const raw = (types[0] as string).trim();
+  const members = splitTopLevel(raw, "|").map((member) => member.trim());
+  const funIndex = members.findIndex((member) => /^fun\s*\(/.test(member));
+  if (funIndex === -1) return null;
+  // Anything unioned before the fun may only be a bare outer nullable.
+  if (members.slice(0, funIndex).some((member) => member !== "nil")) return null;
+  // Rejoin from the fun rightward so a return union or nullable stays whole.
+  const fun = members.slice(funIndex).join("|");
+  const open = fun.indexOf("(");
+  const close = matchBracket(fun, open);
+  if (close === -1) return null;
+  const paramsStr = fun.slice(open + 1, close).trim();
+  const params = paramsStr === "" ? [] : splitTopLevel(paramsStr, ",");
+  const first = (params[0]?.trim() ?? "").length > 0 ? splitTopLevel(params[0] as string, ":") : [];
+  if (first.length < 2) return null;
+  if ((first[0] as string).trim() !== "self") return null;
+  if (first.slice(1).join(":").trim() !== selfTypeName) return null;
+  const afterClose = fun.slice(close + 1).trim();
+  if (afterClose === "") return [];
+  if (afterClose.startsWith(":")) {
+    const retStr = afterClose.slice(1).trim();
+    return retStr === "" ? [] : splitTopLevel(retStr, ",").map((token) => token.trim());
+  }
+  // Anything else after the params `)` must be an outer `| nil` (whole hook optional).
+  const outer = splitTopLevel(afterClose, "|").map((member) => member.trim());
+  return outer.every((member) => member === "" || member === "nil") ? [] : null;
+}

package/scripts/parse-luals.ts

@@ -76,17 +76,27 @@ const emptyPending = (): Pending => ({ doc: [], params: [], returns: [], generic
 /**
  * Read a single raw type token from the head of `rest`, honoring bracket depth so
  * an inner space (`table<string, any>`, `fun(a, b): c`) does not end the token. The
- * token ends at the first top-level whitespace. Returns the token and the trailing
- * remainder (the human description). Never rewrites the token toward TS.
+ * token ends at the first top-level whitespace, except that a space right after a
+ * top-level `:` or `,` continues the token — so a spaced `fun(text_id: string):
+ * string` return arrow and a multi-return `fun(): number, string` separator are kept
+ * whole rather than truncated at the `):`/`,`. Returns the token and the trailing
+ * remainder (the human description). Never rewrites the token toward TS. The only
+ * inputs carrying a top-level `:`/`,` are `fun(...)` type expressions, so plain
+ * types, unions, and descriptions are unaffected.
  */
 function readTypeToken(rest: string): { type: string; rest: string } {
   let depth = 0;
+  let lastNonSpace = "";
   let i = 0;
   for (; i < rest.length; i++) {
     const c = rest[i];
     if (c === "<" || c === "(" || c === "[" || c === "{") depth++;
     else if (c === ">" || c === ")" || c === "]" || c === "}") depth = Math.max(0, depth - 1);
-    else if ((c === " " || c === "\t") && depth === 0) break;
+    else if ((c === " " || c === "\t") && depth === 0) {
+      if (lastNonSpace !== ":" && lastNonSpace !== ",") break;
+      continue;
+    }
+    if (c !== undefined && c !== " " && c !== "\t") lastNonSpace = c;
   }
   return { type: rest.slice(0, i), rest: rest.slice(i).trim() };
 }
@@ -183,15 +193,34 @@ interface FunctionDecl {
   kind: "method" | "module";
   receiver?: string;
   name: string;
+  // A dotted module form (`function T.name`, `T.name = function`) is public module
+  // surface; a bare/`local` form (`function name`, `local function name`) is not.
+  qualified: boolean;
 }
 
-const FUNCTION_FORMS: { re: RegExp; kind: "method" | "module"; recv?: number; name: number }[] = [
+const FUNCTION_FORMS: {
+  re: RegExp;
+  kind: "method" | "module";
+  recv?: number;
+  name: number;
+  qualified?: boolean;
+}[] = [
   { re: /^function\s+([A-Za-z_][\w.]*):([A-Za-z_]\w*)\s*\(/, kind: "method", recv: 1, name: 2 },
-  { re: /^function\s+([A-Za-z_][\w.]*)\.([A-Za-z_]\w*)\s*\(/, kind: "module", name: 2 },
-  { re: /^(?:local\s+)?function\s+([A-Za-z_]\w*)\s*\(/, kind: "module", name: 1 },
+  {
+    re: /^function\s+([A-Za-z_][\w.]*)\.([A-Za-z_]\w*)\s*\(/,
+    kind: "module",
+    name: 2,
+    qualified: true,
+  },
+  { re: /^(?:local\s+)?function\s+([A-Za-z_]\w*)\s*\(/, kind: "module", name: 1, qualified: false },
   { re: /^([A-Za-z_][\w.]*):([A-Za-z_]\w*)\s*=\s*function\b/, kind: "method", recv: 1, name: 2 },
-  { re: /^([A-Za-z_][\w.]*)\.([A-Za-z_]\w*)\s*=\s*function\b/, kind: "module", name: 2 },
-  { re: /^([A-Za-z_]\w*)\s*=\s*function\b/, kind: "module", name: 1 },
+  {
+    re: /^([A-Za-z_][\w.]*)\.([A-Za-z_]\w*)\s*=\s*function\b/,
+    kind: "module",
+    name: 2,
+    qualified: true,
+  },
+  { re: /^([A-Za-z_]\w*)\s*=\s*function\b/, kind: "module", name: 1, qualified: false },
 ];
 
 function parseFunctionDecl(line: string): FunctionDecl | null {
@@ -201,9 +230,9 @@ function parseFunctionDecl(line: string): FunctionDecl | null {
     const name = m[form.name] ?? "";
     if (form.kind === "method") {
       const receiver = form.recv ? m[form.recv] : undefined;
-      return { kind: "method", name, ...(receiver ? { receiver } : {}) };
+      return { kind: "method", name, qualified: true, ...(receiver ? { receiver } : {}) };
     }
-    return { kind: "module", name };
+    return { kind: "module", name, qualified: form.qualified ?? false };
   }
   return null;
 }
@@ -216,6 +245,10 @@ const LOCAL_ASSIGN = /^local\s+([A-Za-z_]\w*)\s*=/;
  * indented lines — in-body closures, `---@cast`/`---@type` narrowing — are opaque,
  * so they neither create declarations nor pollute the pending block. Output order
  * follows source order, making the result stable across repeated runs.
+ *
+ * Only dotted module forms (`function T.name`, `T.name = function`) count as module
+ * surface; a bare or `local function` is a private helper and is skipped. Limitation:
+ * a bare function later re-exported via `M.x = helper` is not recovered as surface.
  */
 export function parseLualsSource(source: string): LibraryModel {
   const interfaces: LibraryInterface[] = [];
@@ -318,7 +351,7 @@ export function parseLualsSource(source: string): LibraryModel {
       if (decl.kind === "method") {
         const target = decl.receiver ? (receiverBinding.get(decl.receiver) ?? decl.receiver) : "";
         ensureInterface(target).methods.push(methodFromPending(decl.name));
-      } else {
+      } else if (decl.qualified) {
         moduleFunctions.push(methodFromPending(decl.name));
       }
       pending = emptyPending();
@@ -379,5 +412,21 @@ export function mergeLibraryModels(models: LibraryModel[]): LibraryModel {
     moduleFunctions.push(...model.moduleFunctions);
   }
 
+  // A class split across fixtures (e.g. druid's curated + runtime `druid.logger`
+  // blocks) concatenates both field sets above, so the same field name can appear
+  // twice with conflicting signatures — an invalid declaration masked by
+  // `skipLibCheck`. Collapse to the first occurrence; methods stay untouched so
+  // overloaded module functions keep every signature.
+  for (const iface of interfaces) iface.fields = dedupeByName(iface.fields);
+
   return { interfaces, aliases, moduleFunctions };
 }
+
+function dedupeByName<T extends { name: string }>(items: T[]): T[] {
+  const seen = new Set<string>();
+  return items.filter((item) => {
+    if (seen.has(item.name)) return false;
+    seen.add(item.name);
+    return true;
+  });
+}