@defold-typescript/library-types 0.23.0 → 0.25.0

package/scripts/emit-library-dts.ts

@@ -15,7 +15,12 @@
  * `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.
+ * only for parents that resolve to a declared interface or an imported external type.
+ *
+ * A token owned by another target is declared through `externalTypes`: the emitter
+ * writes a real `import { <name> } from '<module>';` into the `declare module` block
+ * and resolves the token to that binding, so a cross-library reference carries its
+ * real type instead of lowering to `unknown`.
  */
 
 import {
@@ -26,6 +31,7 @@ import {
   varargElementType,
 } from "@defold-typescript/types";
 import {
+  LUALS_VARARG_TOKEN,
   type MapContext,
   mapLualsCallSignature,
   mapLualsType,
@@ -42,9 +48,20 @@ import type {
   LibraryParam,
 } from "./parse-luals";
 
+/**
+ * A type token owned by another target: the module id that declares it and the name
+ * it exports. Resolving one emits a real `import` into the `declare module` block
+ * rather than lowering the token to `unknown`.
+ */
+export interface ExternalTypeRef {
+  module: string;
+  name: string;
+}
+
 export interface EmitLibraryOptions {
   moduleId: string;
   typeRenames?: Record<string, string>;
+  externalTypes?: Record<string, ExternalTypeRef> | undefined;
 }
 
 const INDENT = "\t";
@@ -85,6 +102,42 @@ function safeParamName(name: string, index: number): string {
   return TS_RESERVED_NAMES.has(name) ? `${name}_` : name;
 }
 
+/**
+ * The token -> local-alias rename map an `externalTypes` config contributes, aliasing
+ * exactly as a declared name would (dotted `event.foo` -> `event_foo`). Shared by the
+ * emitter, the fidelity report, and the api-doc lowering so all three resolve an
+ * external reference to the same identifier the import binds.
+ */
+export function externalTypeRenames(
+  externalTypes?: Record<string, ExternalTypeRef>,
+): Record<string, string> {
+  const renames: Record<string, string> = {};
+  for (const token of Object.keys(externalTypes ?? {})) renames[token] = sanitizeTypeName(token);
+  return renames;
+}
+
+/**
+ * `import { ... } from '<module>';` lines for the external tokens, one per source
+ * module with its names sorted and the modules sorted by id, so re-rendering is
+ * byte-identical. A token whose local alias differs from the export name binds
+ * through an `as` clause.
+ */
+function renderExternalImports(externalTypes?: Record<string, ExternalTypeRef>): string[] {
+  const byModule = new Map<string, Set<string>>();
+  for (const [token, ref] of Object.entries(externalTypes ?? {})) {
+    const alias = sanitizeTypeName(token);
+    const binding = alias === ref.name ? ref.name : `${ref.name} as ${alias}`;
+    const names = byModule.get(ref.module) ?? new Set<string>();
+    names.add(binding);
+    byModule.set(ref.module, names);
+  }
+  return [...byModule.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : 1))
+    .map(
+      ([module, names]) => `${INDENT}import { ${[...names].sort().join(", ")} } from '${module}';`,
+    );
+}
+
 export function mapTypes(types: readonly string[], ctx: MapContext): string {
   if (types.length === 0) return "unknown";
   return types.map((token) => mapLualsType(token, ctx).ts).join(" | ");
@@ -107,24 +160,29 @@ export function renderGenericParams(generics: readonly LibraryGeneric[], ctx: Ma
 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)));
+  return luaMultiReturn(
+    returnTokens.map((token) => mapTypes([token], ctx)),
+    returnTokens.at(-1) === LUALS_VARARG_TOKEN,
+  );
 }
 
 /**
  * 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.
+ * parents that name a declared interface or an imported external type (so no
+ * `extends unknown` is ever emitted), mapped through the rename map; `""` when none
+ * survive.
  */
 function renderExtends(
   iface: LibraryInterface,
   ctx: MapContext,
   interfaceNames: ReadonlySet<string>,
+  externalTokens: ReadonlySet<string>,
 ): string {
   if (!iface.extends) return "";
   const parents = iface.extends
     .split(",")
     .map((name) => name.trim())
-    .filter((name) => interfaceNames.has(name))
+    .filter((name) => interfaceNames.has(name) || externalTokens.has(name))
     .map((name) => mapTypes([name], ctx));
   return parents.length > 0 ? ` extends ${parents.join(", ")}` : "";
 }
@@ -171,16 +229,22 @@ function renderParams(params: readonly LibraryParam[], ctx: MapContext): string
 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)));
+  const last = returns[returns.length - 1] as LibraryParam;
+  const restTail = last.types.length === 1 && last.types[0] === LUALS_VARARG_TOKEN;
+  return luaMultiReturn(
+    returns.map((ret) => mapTypes(ret.types, ctx)),
+    restTail,
+  );
 }
 
-function pushDoc(lines: string[], summary: string, indent: string): void {
-  for (const line of renderDocComment({ summary })) lines.push(`${indent}${line}`);
+function pushDoc(lines: string[], summary: string, indent: string, deprecated?: string): void {
+  const parts = deprecated !== undefined ? { summary, deprecated } : { summary };
+  for (const line of renderDocComment(parts)) lines.push(`${indent}${line}`);
 }
 
 function renderAlias(alias: LibraryAlias, ctx: MapContext): string[] {
   const lines: string[] = [];
-  pushDoc(lines, alias.doc, INDENT);
+  pushDoc(lines, alias.doc, INDENT, alias.deprecated);
   lines.push(`${INDENT}type ${sanitizeTypeName(alias.name)} = ${mapTypes(alias.types, ctx)};`);
   return lines;
 }
@@ -189,12 +253,13 @@ function renderInterface(
   iface: LibraryInterface,
   ctx: MapContext,
   interfaceNames: ReadonlySet<string>,
+  externalTokens: ReadonlySet<string>,
 ): string[] {
   const lines: string[] = [];
-  pushDoc(lines, iface.brief, INDENT);
+  pushDoc(lines, iface.brief, INDENT, iface.deprecated);
   const ifaceCtx = scopeGenerics(ctx, iface.generics);
   const params = renderGenericParams(iface.generics, ifaceCtx);
-  const extendsClause = renderExtends(iface, ifaceCtx, interfaceNames);
+  const extendsClause = renderExtends(iface, ifaceCtx, interfaceNames, externalTokens);
   lines.push(`${INDENT}interface ${sanitizeTypeName(iface.name)}${params}${extendsClause} {`);
   const body = INDENT + INDENT;
   for (const field of iface.fields) {
@@ -216,7 +281,7 @@ function renderInterface(
   }
   for (const method of iface.methods) {
     if (!isPublicMethod(method)) continue;
-    pushDoc(lines, method.brief, body);
+    pushDoc(lines, method.brief, body, method.deprecated);
     const methodCtx = scopeGenerics(ifaceCtx, method.generics);
     const methodParams = renderGenericParams(method.generics, methodCtx);
     lines.push(
@@ -258,7 +323,7 @@ function renderModuleConstants(iface: LibraryInterface, ctx: MapContext): string
 
 function renderModuleFunction(fn: LibraryMethod, ctx: MapContext): string[] {
   const lines: string[] = [];
-  pushDoc(lines, fn.brief, INDENT);
+  pushDoc(lines, fn.brief, INDENT, fn.deprecated);
   const fnCtx = scopeGenerics(ctx, fn.generics);
   const genericParams = renderGenericParams(fn.generics, fnCtx);
   const params = renderParams(fn.params, fnCtx);
@@ -290,6 +355,7 @@ function renderModuleFunction(fn: LibraryMethod, ctx: MapContext): string[] {
 export function buildModelContext(
   model: LibraryModel,
   typeRenames?: Record<string, string>,
+  externalTypes?: Record<string, ExternalTypeRef>,
 ): MapContext {
   const declaredNames = [
     ...model.interfaces.map((iface) => iface.name),
@@ -297,9 +363,18 @@ export function buildModelContext(
   ];
   const nameRenames: Record<string, string> = {};
   for (const name of declaredNames) nameRenames[name] = sanitizeTypeName(name);
+  const externalRenames = externalTypeRenames(externalTypes);
+  for (const [token, alias] of Object.entries(externalRenames)) {
+    const collision = declaredNames.find((name) => sanitizeTypeName(name) === alias);
+    if (collision !== undefined) {
+      throw new Error(
+        `buildModelContext: external type "${token}" resolves to local name "${alias}", which the model already declares as "${collision}".`,
+      );
+    }
+  }
   return {
-    knownNames: new Set(declaredNames),
-    typeRenames: { ...(typeRenames ?? {}), ...nameRenames },
+    knownNames: new Set([...declaredNames, ...Object.values(externalRenames)]),
+    typeRenames: { ...(typeRenames ?? {}), ...externalRenames, ...nameRenames },
   };
 }
 
@@ -310,10 +385,12 @@ export function buildModelContext(
  * `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 ctx = buildModelContext(model, opts.typeRenames, opts.externalTypes);
 
   const interfaceNames = new Set(model.interfaces.map((iface) => iface.name));
+  const externalTokens = new Set(Object.keys(opts.externalTypes ?? {}));
   const out: string[] = ["/** @noResolution */", `declare module '${opts.moduleId}' {`];
+  out.push(...renderExternalImports(opts.externalTypes));
   for (const alias of model.aliases) out.push(...renderAlias(alias, ctx));
   for (const iface of model.interfaces) {
     // The module object's fields become module-level `export const`s (below), so it is
@@ -322,7 +399,7 @@ export function emitLibraryDeclarations(model: LibraryModel, opts: EmitLibraryOp
       out.push(...renderModuleConstants(iface, ctx));
       continue;
     }
-    out.push(...renderInterface(iface, ctx, interfaceNames));
+    out.push(...renderInterface(iface, ctx, interfaceNames, externalTokens));
   }
   for (const fn of model.moduleFunctions) {
     if (!isPublicMethod(fn)) continue;

package/scripts/extract-api-doc.ts

@@ -3,15 +3,19 @@ import ts from "typescript";
 const printer = ts.createPrinter({ removeComments: true });
 
 /**
- * A type node's text as a single comment-free line. The printer re-emits the
- * AST (so a `//`/`/*` inside a string-literal type is never mistaken for a
+ * Any node's text as a single comment-free line. The printer re-emits the AST
+ * (so a `//`/`/*` inside a string-literal type is never mistaken for a
  * comment), then interior whitespace is collapsed so multi-line object literals
  * and wrapped unions no longer leak newlines or member JSDoc into `/api`.
  */
-function typeText(node: ts.TypeNode, sf: ts.SourceFile): string {
+function oneLineText(node: ts.Node, sf: ts.SourceFile): string {
   return printer.printNode(ts.EmitHint.Unspecified, node, sf).replace(/\s+/g, " ").trim();
 }
 
+function typeText(node: ts.TypeNode, sf: ts.SourceFile): string {
+  return oneLineText(node, sf);
+}
+
 interface Field {
   name: string;
   doc: string;
@@ -80,52 +84,88 @@ export function extractApiDoc(source: string, moduleName: string): unknown {
   // vendors both `export function` and bare `function` for the same intent
   // (`rendy.rendy`, `in.onscreen`). With an `export =`, the bare declarations
   // are internal plumbing behind the re-exported value, so they stay unemitted
-  // and the value's interface drives the surface instead (`squid`, `starly`).
+  // and the value's interface drives the surface instead (`squid`).
   const emitBare = !statements.some(ts.isExportAssignment);
 
   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 +185,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 +193,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 {
@@ -170,6 +254,21 @@ export function extractApiDoc(source: string, moduleName: string): unknown {
   };
 }
 
+/**
+ * A declaration's type parameter list as the pre-rendered string the sibling
+ * `lower-api-doc` lane emits (`<T>`, `<T = unknown>`, `<A, B extends A>`), or
+ * `""` when there is none — absence of the key, not an empty string, is how the
+ * model encodes "takes no type arguments".
+ */
+function genericClause(
+  decl: ts.FunctionDeclaration | ts.MethodSignature,
+  sf: ts.SourceFile,
+): string {
+  const params = decl.typeParameters;
+  if (!params || params.length === 0) return "";
+  return `<${params.map((p) => oneLineText(p, sf)).join(", ")}>`;
+}
+
 function functionElement(
   decl: ts.FunctionDeclaration | ts.MethodSignature,
   name: string,
@@ -204,14 +303,17 @@ function functionElement(
         ];
 
   const example = exampleText(decl);
+  const generics = genericClause(decl, sf);
   return {
     type: "FUNCTION",
     name,
     brief: briefOf(summary),
     description: summary,
+    ...(generics === "" ? {} : { generics }),
     parameters,
     returnvalues,
     ...(example === "" ? {} : { examples: example }),
+    ...deprecatedKey(decl),
   };
 }
 
@@ -225,13 +327,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 +355,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 +491,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 +512,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 +565,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*/, "");