@defold-typescript/library-types 0.22.0 → 0.24.0

package/scripts/lower-api-doc.ts

@@ -15,34 +15,37 @@
 
 import {
   buildModelContext,
+  type ExternalTypeRef,
+  isPublicField,
+  isPublicMethod,
   mapTypes,
+  paramOptionalFlags,
   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> {
+function parameterElement(
+  param: LibraryParam,
+  isOptional: boolean,
+  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.
+  // `isOptional` comes from the emitter's trailing-run rule (paramOptionalFlags), not
+  // `param.isOptional` alone, so the `/api` signature matches the emitted `.d.ts`.
   return {
     name: param.isVararg ? "...args" : param.name,
     doc: param.doc,
     types: mapTokens(param.types, ctx),
-    is_optional: param.isOptional ? "True" : "False",
+    is_optional: isOptional ? "True" : "False",
     is_vararg: param.isVararg ? "True" : "False",
   };
 }
@@ -54,17 +57,24 @@ function returnElement(ret: LibraryParam, ctx: MapContext): Record<string, unkno
 function functionElement(method: LibraryMethod, ctx: MapContext): Record<string, unknown> {
   const fnCtx = scopeGenerics(ctx, method.generics);
   const generics = renderGenericParams(method.generics, fnCtx);
+  const optionalFlags = paramOptionalFlags(method.params);
   return {
     type: "FUNCTION",
     name: method.name,
     brief: method.brief,
     description: method.brief,
     ...(generics !== "" ? { generics } : {}),
-    parameters: method.params.map((param) => parameterElement(param, fnCtx)),
+    parameters: method.params.map((param, index) =>
+      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,
@@ -74,20 +84,52 @@ function propertyElement(field: LibraryField, ctx: MapContext): Record<string, u
   };
 }
 
+// A module object's field lowered as a top-level `VARIABLE` — the ref-doc shape for a
+// module constant (`squid.TRACE`), matching the emitter's module-level `export const`.
+function variableElement(field: LibraryField, ctx: MapContext): Record<string, unknown> {
+  return {
+    type: "VARIABLE",
+    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> },
+  {
+    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) {
+    if (!isPublicMethod(fn)) continue;
     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));
+    // The module object's public fields are module-level constants, lowered as top-level
+    // VARIABLE elements rather than a TYPEDEF named after the class.
+    if (iface.name === model.moduleObject) {
+      for (const field of iface.fields) {
+        if (!isPublicField(field)) continue;
+        elements.push(variableElement(field, ifaceCtx));
+      }
+      continue;
+    }
+    const functions = iface.methods
+      .filter(isPublicMethod)
+      .map((method) => functionElement(method, ifaceCtx));
     const properties = iface.fields
       .filter(isPublicField)
       .map((field) => propertyElement(field, ifaceCtx));
@@ -96,18 +138,26 @@ 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` (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);
+  // The module's own `@class` 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.
+  // A tracked `moduleObject` names it directly (squid's `Squid` != namespace `squid`);
+  // otherwise fall back to the class named for the namespace (`@class druid`).
+  const moduleClass = model.interfaces.find(
+    (iface) => iface.name === (model.moduleObject ?? namespace),
+  );
   const description = moduleClass?.brief ?? "";
   const brief = description.split("\n")[0] ?? "";
 

package/scripts/luals-fidelity.ts

@@ -10,6 +10,12 @@
  * sorted-unique token list so the gap is visible instead of silent.
  */
 
+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";
 
@@ -28,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;
@@ -80,12 +86,17 @@ export function buildFidelityReport(
       );
     }
     mapConstraints(iface.generics, ifaceCtx);
+    // A class `@overload fun(...)` is emitted as a call signature, so its type token
+    // counts toward coverage exactly like a field or method type.
+    for (const overload of iface.overloads ?? []) mapTokens([overload.type], ifaceCtx);
     for (const field of iface.fields) {
+      if (!isPublicField(field)) continue;
       totalMembers++;
       if (undocumented(field.doc)) undocumentedMembers++;
       mapTokens(field.types, ifaceCtx);
     }
     for (const method of iface.methods) {
+      if (!isPublicMethod(method)) continue;
       totalMembers++;
       if (undocumented(method.brief)) undocumentedMembers++;
       const methodCtx = scopeGenerics(ifaceCtx, method.generics);
@@ -96,6 +107,7 @@ export function buildFidelityReport(
   }
 
   for (const fn of model.moduleFunctions) {
+    if (!isPublicMethod(fn)) continue;
     totalMembers++;
     if (undocumented(fn.brief)) undocumentedMembers++;
     const fnCtx = scopeGenerics(ctx, fn.generics);

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
@@ -126,7 +145,17 @@ function needsArrayParens(tsExpr: string): boolean {
   );
 }
 
-function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string {
+/**
+ * The mapped `(params)` list and `ret` type of a `fun(...)` token, shared by the
+ * arrow-form `mapFunction` and the colon-return `mapLualsCallSignature`. The only
+ * difference between the two consumers is the separator (`=>` vs `:`), so both the
+ * param handling (typed/untyped/vararg) and the single/multi-return logic live here.
+ */
+function functionParts(
+  token: string,
+  ctx: MapContext,
+  unknowns: string[],
+): { paramList: string; ret: string } {
   const open = token.indexOf("(");
   const close = matchBracket(token, open);
   const paramsStr = token.slice(open + 1, close).trim();
@@ -136,21 +165,18 @@ function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string
   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() ?? "";
@@ -167,10 +193,18 @@ function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string
     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 };
+}
+
+function mapFunction(token: string, ctx: MapContext, unknowns: string[]): string {
+  const { paramList, ret } = functionParts(token, ctx, unknowns);
   return `(${paramList}) => ${ret}`;
 }
 
@@ -200,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("("));
@@ -218,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) {
@@ -248,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;
@@ -275,6 +321,24 @@ export function mapLualsType(token: string, ctx: MapContext): MapResult {
   return { ts, unknowns };
 }
 
+/**
+ * Map a `fun(...)` token (a class `@overload`) to a TypeScript **call signature** —
+ * the colon-return form `(params): ret` an interface uses to become callable, not
+ * the `=>` arrow a field/param function type takes. Shares the exact param/return
+ * computation as `mapFunction`, so nested callback params and multi-returns map
+ * identically. Throws on a non-`fun` token; the parser only ever records `fun(...)`
+ * overloads, so this guards a programming error rather than user input.
+ */
+export function mapLualsCallSignature(token: string, ctx: MapContext): MapResult {
+  const trimmed = token.trim();
+  if (!/^fun\s*\(/.test(trimmed)) {
+    throw new Error(`mapLualsCallSignature: expected a "fun(...)" token, got "${token}".`);
+  }
+  const unknowns: string[] = [];
+  const { paramList, ret } = functionParts(trimmed, ctx, unknowns);
+  return { ts: `(${paramList}): ${ret}`, unknowns };
+}
+
 /**
  * When `types` is exactly one `fun(self: <selfTypeName>, ...)` token — optionally
  * unioned with `nil` — whose first parameter is `self` typed as the enclosing

package/scripts/parse-lua-surface.ts

@@ -0,0 +1,187 @@
+/**
+ * A line-oriented reader for the *public surface* of a plain-Lua module — the
+ * member names and parameter names a `local M = {} … return M` file declares.
+ *
+ * `sync-authored-types.ts` gates the authored/forked lane on a forked-vs-generated
+ * identity diff and records that there is no coverage comparison against a primary
+ * source. That holds for *types*: upstream Lua declares none. It does not hold for
+ * *surface*: names and arity are right there in the source, so a fork that drops a
+ * member or a trailing parameter is measurable. This module reads that side; the
+ * comparison lives in `authored-parity.ts`.
+ *
+ * The corpus is a handful of pinned files, so line scanning is what it needs — a
+ * Lua grammar would buy nothing here. Two rules keep it honest:
+ *
+ * - **Column 0 only.** A definition is a member when it starts the line. This is
+ *   what keeps `nakama/util/log.lua`'s `M.log = noop` — reassigned inside three
+ *   different function bodies — out of the surface, and it is why the reader never
+ *   needs to know where a block ends.
+ * - **Loud failure over silent undercount.** A missing `return <name>` or a
+ *   parameter list that does not close on its own line throws, as does a
+ *   `return setmetatable(M, …)` whose metatable carries `__index` or is named by a
+ *   variable whose keys this reader cannot see — either could add members no column-0
+ *   scan will find. The whole point of the instrument is that a dropped member is
+ *   visible; a parser that quietly skips what it cannot read would inflate every
+ *   coverage number it feeds.
+ */
+
+export interface LuaMember {
+  name: string;
+  /** Absent for a non-callable field (`M.SOME_CONSTANT = "X"`), so a field can
+   * never be confused with a zero-arity function. */
+  params?: string[];
+  /** True when the definition ends in `...`, which is not a named parameter. */
+  varargs: boolean;
+  /** The `---` LuaDoc block immediately above the definition, comment markers
+   * stripped, one interior blank line crossed; empty when the block is absent or
+   * opens with a plain `--`. */
+  doc: string;
+  /** True when a comment block *was* there and the `---` rule declined it, which `doc`
+   * alone cannot say — an empty `doc` otherwise means upstream documented nothing. */
+  refusedDoc: boolean;
+}
+
+export interface LuaSurface {
+  moduleLocal: string;
+  members: LuaMember[];
+}
+
+const RETURN_LINE = /^return\s+([A-Za-z_][A-Za-z0-9_]*)\s*;?\s*$/;
+const RETURN_SETMETATABLE = /^return\s+setmetatable\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,/;
+const IDENTIFIER = "[A-Za-z_][A-Za-z0-9_]*";
+
+/** The metatable argument of a `return setmetatable(<name>, …)`, refused unless its
+ * keys are readable and none of them delegates. `text` runs from the comma to the end
+ * of the source rather than to the matching brace: over-reading can only refuse a file
+ * loudly, where under-reading would accept a delegating module and report its short
+ * surface as complete. */
+function assertNoDelegation(text: string): void {
+  if (text.trimStart().startsWith("{") === false) {
+    throw new Error(
+      "lua surface: the returned `setmetatable` is given a metatable this reader cannot see the keys of, so a delegated member would be invisible — inline the table literal or measure the module another way.",
+    );
+  }
+  if (text.includes("__index")) {
+    throw new Error(
+      "lua surface: the returned metatable carries `__index`, so members reached through it would be invisible to a column-0 scan and the surface would read as complete while short.",
+    );
+  }
+}
+
+function resolveModuleLocal(lines: string[]): string {
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index] as string;
+    const bare = RETURN_LINE.exec(line);
+    if (bare) return bare[1] as string;
+    const wrapped = RETURN_SETMETATABLE.exec(line);
+    if (wrapped) {
+      assertNoDelegation(
+        [line.slice((wrapped[0] as string).length), ...lines.slice(index + 1)].join("\n"),
+      );
+      return wrapped[1] as string;
+    }
+  }
+  throw new Error(
+    "lua surface: the source has no trailing `return <name>`, so the module-local name cannot be derived.",
+  );
+}
+
+/** The parameter names between the parentheses opened at `open` on `line`, with a
+ * `...` tail reported separately. Throws when the list does not close on the same
+ * line rather than dropping the member. */
+function readParams(
+  line: string,
+  open: number,
+  lineNumber: number,
+): { params: string[]; varargs: boolean } {
+  const close = line.indexOf(")", open);
+  if (close === -1) {
+    throw new Error(
+      `lua surface: line ${lineNumber} opens a parameter list that does not close on the same line — ${line.trim()}`,
+    );
+  }
+  const raw = line
+    .slice(open + 1, close)
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part !== "");
+  return { params: raw.filter((part) => part !== "..."), varargs: raw.includes("...") };
+}
+
+/** The contiguous run of comment lines ending at `index - 1`, in source order. */
+function readSegment(lines: string[], index: number): string[] {
+  const segment: string[] = [];
+  for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+    const line = (lines[cursor] as string).trim();
+    if (!line.startsWith("--") || line.startsWith("--[[")) break;
+    segment.unshift(line);
+  }
+  return segment;
+}
+
+/** The contiguous comment block ending at `index - 1`, kept only when it opens
+ * with `---`. LuaDoc in this corpus is a `---` summary followed by plain `--`
+ * `@param`/`@return` lines, so the marker on the *first* line is what decides.
+ *
+ * A single blank line inside the run is crossed, and only when the segment
+ * attached to the definition opens no block of its own — upstream wraps a long
+ * `@param` list around a blank, which would otherwise truncate the block to its
+ * tag half and lose the summary above. A segment carrying its own `---` is never
+ * absorbed into the one below it, so a blank-separated section header stays out. */
+function readDoc(lines: string[], index: number): Pick<LuaMember, "doc" | "refusedDoc"> {
+  const attached = readSegment(lines, index);
+  if (attached.length === 0) return { doc: "", refusedDoc: false };
+  const above = index - attached.length - 1;
+  const block =
+    attached.some((line) => line.startsWith("---")) ||
+    above < 0 ||
+    (lines[above] as string).trim() !== ""
+      ? attached
+      : [...readSegment(lines, above), ...attached];
+  if (!(block[0] as string).startsWith("---")) return { doc: "", refusedDoc: true };
+  const doc = block
+    .map((line) => line.replace(/^-+\s?/, "").trimEnd())
+    .join("\n")
+    .trim();
+  return { doc, refusedDoc: false };
+}
+
+/**
+ * The public surface of a Lua module source: the module-local name it returns and
+ * every member assigned to it at column 0, in source order. A name defined more
+ * than once keeps its first position and its last definition, matching Lua.
+ */
+export function parseLuaSurface(source: string): LuaSurface {
+  const lines = source.split("\n");
+  const moduleLocal = resolveModuleLocal(lines);
+  const definition = new RegExp(`^function\\s+${moduleLocal}\\.(${IDENTIFIER})\\s*\\(`);
+  const assignment = new RegExp(`^${moduleLocal}\\.(${IDENTIFIER})\\s*=\\s*(.*)$`);
+  const assignedFunction = /^function\s*\(/;
+
+  const members = new Map<string, LuaMember>();
+  const record = (member: LuaMember): void => {
+    members.set(member.name, member);
+  };
+
+  for (const [index, line] of lines.entries()) {
+    const defined = definition.exec(line);
+    if (defined) {
+      const { params, varargs } = readParams(line, defined[0].length - 1, index + 1);
+      record({ name: defined[1] as string, params, varargs, ...readDoc(lines, index) });
+      continue;
+    }
+    const assigned = assignment.exec(line);
+    if (!assigned) continue;
+    const name = assigned[1] as string;
+    const rhs = assigned[2] as string;
+    if (!assignedFunction.test(rhs)) {
+      record({ name, varargs: false, ...readDoc(lines, index) });
+      continue;
+    }
+    const open = line.indexOf("(", line.length - rhs.length);
+    const { params, varargs } = readParams(line, open, index + 1);
+    record({ name, params, varargs, ...readDoc(lines, index) });
+  }
+
+  return { moduleLocal, members: [...members.values()] };
+}