@defold-typescript/library-types 0.22.0 → 0.24.0

package/scripts/extract-api-doc.ts

@@ -86,46 +86,82 @@ export function extractApiDoc(source: string, moduleName: string): unknown {
   const elements: Record<string, unknown>[] = [];
   const emittedNames = new Set<string>();
   const referencedTypeNodes: ts.TypeNode[] = [];
+  // Type nodes reached from file-scope declarations, kept apart from the module
+  // block's so an ambient global can never pull a module-block shape onto `/api`
+  // that the module surface alone did not reach.
+  const globalTypeNodes: ts.TypeNode[] = [];
+  // Each alias's declaration paired with the bare element it already pushed, so
+  // a reachable object-literal alias is filled in by merging into that element
+  // rather than by appending a second one — element order stays as emitted.
+  const aliasElements: { node: ts.TypeAliasDeclaration; element: Record<string, unknown> }[] = [];
 
   // Members nested in an `export namespace` (`bridge.bridge`) keep their
   // namespace path so same-named members across namespaces (e.g. `is_supported`)
   // stay distinct instead of colliding in `emittedNames`.
-  const collect = (nodes: readonly ts.Statement[], prefix: string): void => {
+  //
+  // `global` switches the walk to the ambient lane: the file's own statements
+  // rather than the module block's. There the gate is the `declare` modifier
+  // (there is no `export =` to suppress bare declarations, so `emitBare` does not
+  // apply), each element carries the `global` marker, and a type alias is not
+  // pushed eagerly — file scope carries far more incidental type machinery than a
+  // module block, so a shape publishes only once reachability proves a published
+  // signature names it.
+  const collect = (nodes: readonly ts.Statement[], prefix: string, global: boolean): void => {
     const qualify = (name: string): string => (prefix ? `${prefix}.${name}` : name);
+    const mark = global ? { global: true } : {};
+    const typeNodes = global ? globalTypeNodes : referencedTypeNodes;
+    // Inside an ambient namespace every member is ambient by containment, so the
+    // nested lane emits regardless of an `export` keyword.
+    const gate = (stmt: ts.HasModifiers): boolean =>
+      global ? prefix !== "" || isAmbient(stmt) || isExported(stmt) : isExported(stmt) || emitBare;
     for (const stmt of nodes) {
-      if (ts.isFunctionDeclaration(stmt) && stmt.name && (isExported(stmt) || emitBare)) {
-        collectFunctionReferenceTypes(stmt, referencedTypeNodes);
+      if (ts.isFunctionDeclaration(stmt) && stmt.name && gate(stmt)) {
+        collectFunctionReferenceTypes(stmt, typeNodes);
         const name = qualify(stmt.name.text);
-        elements.push(functionElement(stmt, name, sf));
+        elements.push({ ...functionElement(stmt, name, sf), ...mark });
         emittedNames.add(name);
-      } else if (ts.isVariableStatement(stmt) && (isExported(stmt) || emitBare)) {
+      } else if (ts.isVariableStatement(stmt) && gate(stmt)) {
+        // The `VariableStatement` carries the JSDoc, not the declaration, so both the
+        // summary and the deprecation tag are read once from the statement and shared
+        // by every declarator under it.
+        const summary = jsDocSummary(stmt);
         for (const decl of stmt.declarationList.declarations) {
-          if (decl.type) referencedTypeNodes.push(decl.type);
+          if (decl.type) typeNodes.push(decl.type);
           const fields = objectFields(decl.type, sf);
           const name = qualify(decl.name.getText(sf));
           elements.push({
             type: "VARIABLE",
             name,
+            // Unconditional, matching `functionElement`: an absent key and an empty one
+            // would be two shapes the docs-site had to tell apart for no gain.
+            brief: briefOf(summary),
+            description: summary,
             types: decl.type ? [typeText(decl.type, sf)] : [],
             ...(fields ? { fields } : {}),
+            ...deprecatedKey(stmt),
+            ...mark,
           });
           emittedNames.add(name);
         }
       } else if (ts.isTypeAliasDeclaration(stmt)) {
+        if (global) continue;
         const name = qualify(stmt.name.text);
-        elements.push({ type: "TYPEDEF", name });
+        const element: Record<string, unknown> = { type: "TYPEDEF", name };
+        elements.push(element);
         emittedNames.add(name);
+        aliasElements.push({ node: stmt, element });
       } else if (
         ts.isModuleDeclaration(stmt) &&
+        !ts.isStringLiteral(stmt.name) &&
         stmt.body &&
         ts.isModuleBlock(stmt.body) &&
-        (isExported(stmt) || emitBare)
+        gate(stmt)
       ) {
-        collect(stmt.body.statements, qualify(stmt.name.getText(sf)));
+        collect(stmt.body.statements, qualify(stmt.name.getText(sf)), global);
       }
     }
   };
-  collect(statements, "");
+  collect(statements, "", false);
 
   const moduleValueInterfaces = exportedValueInterfaces(moduleBlock);
   for (const iface of moduleValueInterfaces) {
@@ -145,6 +181,7 @@ export function extractApiDoc(source: string, moduleName: string): unknown {
           name,
           types: member.type ? [typeText(member.type, sf)] : [],
           ...(fields ? { fields } : {}),
+          ...deprecatedKey(member),
         });
         emittedNames.add(name);
       }
@@ -152,16 +189,59 @@ export function extractApiDoc(source: string, moduleName: string): unknown {
   }
 
   const moduleValueInterfaceNames = new Set(moduleValueInterfaces.map((iface) => iface.name.text));
-  for (const iface of referencedInterfaces(
-    moduleBlock,
-    referencedTypeNodes,
-    moduleValueInterfaceNames,
-  )) {
-    if (emittedNames.has(iface.name.text)) continue;
+  const declared = moduleBlock ? moduleTypeDeclarations(moduleBlock) : undefined;
+  const reachable = referencedTypeNames(declared, referencedTypeNodes);
+
+  for (const { node, element } of aliasElements) {
+    const name = node.name.text;
+    // Reachability is resolved against the module block, so identity keeps a
+    // same-named alias nested in a namespace from borrowing the outer one's.
+    if (declared?.aliases.get(name) !== node) continue;
+    if (!reachable.has(name) || !ts.isTypeLiteralNode(node.type)) continue;
+    const { functions, properties } = shapeMembers(node.type.members, sf);
+    if (functions.length > 0) element.functions = functions;
+    if (properties.length > 0) element.properties = properties;
+  }
+
+  for (const name of reachable) {
+    if (moduleValueInterfaceNames.has(name) || emittedNames.has(name)) continue;
+    const iface = declared?.interfaces.get(name);
+    if (!iface) continue;
     const typedef = typedefElement(iface, sf);
     if (!typedef) continue;
     elements.push(typedef);
-    emittedNames.add(iface.name.text);
+    emittedNames.add(name);
+  }
+
+  // The ambient lane runs last so every module-block element keeps the index it
+  // has today. Its shapes resolve against file-scope declarations only, by node
+  // identity, so a file-scope shape never borrows a same-named module-block one.
+  collect(sf.statements, "", true);
+  const globalDeclared = typeDeclarationsIn(sf.statements);
+  for (const name of referencedTypeNames(globalDeclared, globalTypeNodes)) {
+    if (emittedNames.has(name)) continue;
+    const alias = globalDeclared.aliases.get(name);
+    if (alias) {
+      if (!ts.isTypeLiteralNode(alias.type)) continue;
+      const { functions, properties } = shapeMembers(alias.type.members, sf);
+      if (functions.length === 0 && properties.length === 0) continue;
+      elements.push({
+        type: "TYPEDEF",
+        name,
+        ...(functions.length > 0 ? { functions } : {}),
+        ...(properties.length > 0 ? { properties } : {}),
+        ...deprecatedKey(alias),
+        global: true,
+      });
+      emittedNames.add(name);
+      continue;
+    }
+    const iface = globalDeclared.interfaces.get(name);
+    if (!iface) continue;
+    const typedef = typedefElement(iface, sf);
+    if (!typedef) continue;
+    elements.push({ ...typedef, global: true });
+    emittedNames.add(name);
   }
 
   return {
@@ -212,6 +292,7 @@ function functionElement(
     parameters,
     returnvalues,
     ...(example === "" ? {} : { examples: example }),
+    ...deprecatedKey(decl),
   };
 }
 
@@ -225,13 +306,22 @@ function collectFunctionReferenceTypes(
   if (decl.type) out.push(decl.type);
 }
 
-function typedefElement(
-  iface: ts.InterfaceDeclaration,
-  sf: ts.SourceFile,
-): Record<string, unknown> | undefined {
+interface ShapeMembers {
+  functions: Record<string, unknown>[];
+  properties: Record<string, unknown>[];
+}
+
+/**
+ * The one member reader shared by both shape carriers — an `interface`
+ * declaration and a `type X = { … }` alias — so the two lanes cannot drift.
+ * `is_optional` is written only on an optional member, matching how
+ * `deprecatedKey` encodes absence and keeping a regen diff proportional to what
+ * actually changed.
+ */
+function shapeMembers(members: readonly ts.TypeElement[], sf: ts.SourceFile): ShapeMembers {
   const functions: Record<string, unknown>[] = [];
   const properties: Record<string, unknown>[] = [];
-  for (const member of iface.members) {
+  for (const member of members) {
     if (!member.name) continue;
     const name = memberName(member.name, sf);
     if (ts.isMethodSignature(member)) {
@@ -244,50 +334,80 @@ function typedefElement(
         brief: briefOf(summary),
         description: summary,
         types: member.type ? [typeText(member.type, sf)] : [],
+        ...(member.questionToken ? { is_optional: "True" } : {}),
         ...(fields ? { fields } : {}),
+        ...deprecatedKey(member),
       });
     }
   }
+  return { functions, properties };
+}
+
+function typedefElement(
+  iface: ts.InterfaceDeclaration,
+  sf: ts.SourceFile,
+): Record<string, unknown> | undefined {
+  const { functions, properties } = shapeMembers(iface.members, sf);
   if (functions.length === 0 && properties.length === 0) return undefined;
   return {
     type: "TYPEDEF",
     name: iface.name.text,
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
+    ...deprecatedKey(iface),
   };
 }
 
-function referencedInterfaces(
-  moduleBlock: ts.ModuleBlock | undefined,
-  typeNodes: ts.TypeNode[],
-  excludedNames: ReadonlySet<string>,
-): ts.InterfaceDeclaration[] {
-  if (!moduleBlock) return [];
+interface TypeDeclarations {
+  aliases: Map<string, ts.TypeAliasDeclaration>;
+  interfaces: Map<string, ts.InterfaceDeclaration>;
+}
+
+function typeDeclarationsIn(statements: readonly ts.Statement[]): TypeDeclarations {
   const aliases = new Map<string, ts.TypeAliasDeclaration>();
   const interfaces = new Map<string, ts.InterfaceDeclaration>();
-  for (const stmt of moduleBlock.statements) {
+  for (const stmt of statements) {
     if (ts.isTypeAliasDeclaration(stmt)) aliases.set(stmt.name.text, stmt);
     if (ts.isInterfaceDeclaration(stmt)) interfaces.set(stmt.name.text, stmt);
   }
+  return { aliases, interfaces };
+}
+
+function moduleTypeDeclarations(moduleBlock: ts.ModuleBlock): TypeDeclarations {
+  return typeDeclarationsIn(moduleBlock.statements);
+}
+
+/**
+ * Every alias and interface name declared in `declared` that is reachable from
+ * an emitted member's type, in first-reached order. Both shape lanes gate on
+ * this single traversal — a reachable interface becomes its own TYPEDEF element,
+ * a reachable alias over an object literal has that element's members filled in
+ * — so a shape no published member names stays off `/api` either way. The
+ * module-block and file-scope lanes each pass their own declarations, so a name
+ * declared in both resolves to the lane that named it.
+ */
+function referencedTypeNames(
+  declared: TypeDeclarations | undefined,
+  typeNodes: ts.TypeNode[],
+): Set<string> {
+  const names = new Set<string>();
+  if (!declared) return names;
+  const { aliases, interfaces } = declared;
 
-  const found = new Map<string, ts.InterfaceDeclaration>();
-  const seenAliases = new Set<string>();
   const visit = (node: ts.Node): void => {
     if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
       const name = node.typeName.text;
-      const iface = interfaces.get(name);
-      if (iface && !excludedNames.has(name)) found.set(name, iface);
       const alias = aliases.get(name);
-      if (alias && !seenAliases.has(name)) {
-        seenAliases.add(name);
-        visit(alias.type);
+      if ((alias || interfaces.has(name)) && !names.has(name)) {
+        names.add(name);
+        if (alias) visit(alias.type);
       }
     }
     ts.forEachChild(node, visit);
   };
 
   for (const node of typeNodes) visit(node);
-  return [...found.values()];
+  return names;
 }
 
 function exportedValueInterfaces(
@@ -350,9 +470,17 @@ function memberName(name: ts.PropertyName, sf: ts.SourceFile): string {
   return name.getText(sf);
 }
 
+// string-named only: a file-scope `declare namespace` is a `ModuleDeclaration`
+// too, so an identifier-named block appearing before the real `declare
+// module '<name>'` would otherwise be mistaken for the module surface.
 function findModuleBlock(sf: ts.SourceFile): ts.ModuleBlock | undefined {
   for (const stmt of sf.statements) {
-    if (ts.isModuleDeclaration(stmt) && stmt.body && ts.isModuleBlock(stmt.body)) {
+    if (
+      ts.isModuleDeclaration(stmt) &&
+      ts.isStringLiteral(stmt.name) &&
+      stmt.body &&
+      ts.isModuleBlock(stmt.body)
+    ) {
       return stmt.body;
     }
   }
@@ -363,6 +491,10 @@ function isExported(node: ts.HasModifiers): boolean {
   return (ts.getCombinedModifierFlags(node as ts.Declaration) & ts.ModifierFlags.Export) !== 0;
 }
 
+function isAmbient(node: ts.HasModifiers): boolean {
+  return (ts.getCombinedModifierFlags(node as ts.Declaration) & ts.ModifierFlags.Ambient) !== 0;
+}
+
 /** The closest non-empty JSDoc summary text attached to a node, tags stripped. */
 function jsDocSummary(node: ts.Node): string {
   const comments = ts
@@ -412,6 +544,25 @@ function exampleText(decl: ts.FunctionDeclaration | ts.MethodSignature): string
   return "";
 }
 
+// `undefined` when the node carries no `@deprecated`, the trimmed tag text when
+// it does — `""` for a bare tag. The caller spreads the key only on a defined
+// result, so absence of the key is the sole encoding of "not deprecated" and a
+// bare tag stays distinguishable from an untagged symbol.
+function deprecatedText(node: ts.Node): string | undefined {
+  for (const tag of ts.getJSDocTags(node)) {
+    if (tag.tagName.text === "deprecated") {
+      return (ts.getTextOfJSDocComment(tag.comment) ?? "").trim();
+    }
+  }
+  return undefined;
+}
+
+/** The `{ deprecated }` key to spread onto an element, empty when untagged. */
+function deprecatedKey(node: ts.Node): Record<string, string> {
+  const text = deprecatedText(node);
+  return text === undefined ? {} : { deprecated: text };
+}
+
 /** Trim a JSDoc `@param`/`@returns` comment and drop a leading `-` delimiter. */
 function cleanDoc(comment: string | undefined): string {
   return (comment ?? "").trim().replace(/^-\s*/, "");

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);
+  });
+}