@cosmicdrift/kumiko-guards 0.398.0 → 0.400.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.398.0",
+  "version": "0.400.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.398.0",
+    "@cosmicdrift/kumiko-types": "0.400.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },
@@ -52,7 +52,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.398.0"
+    "@cosmicdrift/kumiko-framework": "0.400.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -60,6 +60,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.398.0"
+    "@cosmicdrift/kumiko-framework": "0.400.0"
   }
 }

package/src/_lib/agent-docs-api-nodes.ts

@@ -0,0 +1,107 @@
+import {
+  type ArrowFunction,
+  type ClassDeclaration,
+  type EnumDeclaration,
+  type FunctionDeclaration,
+  type FunctionExpression,
+  type InterfaceDeclaration,
+  type JSDoc,
+  Node,
+  SyntaxKind,
+  type TypeAliasDeclaration,
+  type VariableDeclaration,
+} from "ts-morph";
+
+export type ApiTypeDeclaration =
+  | InterfaceDeclaration
+  | TypeAliasDeclaration
+  | EnumDeclaration
+  | ClassDeclaration;
+
+export function isApiTypeDeclaration(node: Node): node is ApiTypeDeclaration {
+  return (
+    Node.isInterfaceDeclaration(node) ||
+    Node.isTypeAliasDeclaration(node) ||
+    Node.isEnumDeclaration(node) ||
+    Node.isClassDeclaration(node)
+  );
+}
+
+export function jsDocsOf(node: Node): readonly JSDoc[] {
+  if (Node.isVariableDeclaration(node)) return node.getVariableStatement()?.getJsDocs() ?? [];
+  return Node.isJSDocable(node) ? node.getJsDocs() : [];
+}
+
+export function isInternalApi(node: Node): boolean {
+  return jsDocsOf(node).some((doc) => doc.getTags().some((tag) => tag.getTagName() === "internal"));
+}
+
+export function isPublicClassMember(member: Node): boolean {
+  if (isInternalApi(member)) return false;
+  if (!Node.isModifierable(member)) return true;
+  if (
+    member.hasModifier(SyntaxKind.PrivateKeyword) ||
+    member.hasModifier(SyntaxKind.ProtectedKeyword)
+  )
+    return false;
+  return (
+    !(Node.isPropertyDeclaration(member) || Node.isMethodDeclaration(member)) ||
+    !member.getName().startsWith("#")
+  );
+}
+
+function presentNodes(node: Node | undefined): Node[] {
+  return node === undefined ? [] : [node];
+}
+
+function isFunctionLike(node: Node | undefined): node is ArrowFunction | FunctionExpression {
+  return Node.isArrowFunction(node) || Node.isFunctionExpression(node);
+}
+
+function variableTypeRoots(node: VariableDeclaration): Node[] {
+  const typeNode = node.getTypeNode();
+  if (typeNode !== undefined) return [typeNode];
+  const initializer = node.getInitializer();
+  if (!isFunctionLike(initializer)) return [];
+  return [...initializer.getParameters(), ...presentNodes(initializer.getReturnTypeNode())];
+}
+
+function functionTypeRoots(node: FunctionDeclaration): Node[] {
+  const overloads = node.getOverloads();
+  return (overloads.length > 0 ? overloads : [node]).flatMap((signature) => [
+    ...signature.getParameters(),
+    ...presentNodes(signature.getReturnTypeNode()),
+    ...signature.getTypeParameters(),
+  ]);
+}
+
+function classTypeRoots(node: ClassDeclaration): Node[] {
+  const roots: Node[] = presentNodes(node.getExtends());
+  for (const member of node.getMembers()) {
+    if (!isPublicClassMember(member)) continue;
+    if (Node.isPropertyDeclaration(member)) roots.push(...presentNodes(member.getTypeNode()));
+    if (Node.isMethodDeclaration(member) || Node.isConstructorDeclaration(member)) {
+      roots.push(...member.getParameters(), ...presentNodes(member.getReturnTypeNode()));
+    }
+  }
+  return roots;
+}
+
+function typeRoots(node: Node): Node[] {
+  if (Node.isVariableDeclaration(node)) return variableTypeRoots(node);
+  if (Node.isFunctionDeclaration(node)) return functionTypeRoots(node);
+  if (Node.isClassDeclaration(node)) return classTypeRoots(node);
+  return isApiTypeDeclaration(node) ? [node] : [];
+}
+
+// Type references reachable from the rendered text: parameter, return, property
+// and heritage types. Bodies and initializers are not walked.
+export function referencedTypeNodes(node: Node): readonly Node[] {
+  const roots = typeRoots(node);
+  return roots.flatMap((root) => [
+    ...(Node.isTypeReference(root) || Node.isExpressionWithTypeArguments(root) ? [root] : []),
+    ...root.getDescendantsOfKind(SyntaxKind.TypeReference),
+    ...root.getDescendantsOfKind(SyntaxKind.ExpressionWithTypeArguments),
+    ...root.getDescendantsOfKind(SyntaxKind.TypeQuery),
+  ]);
+}

package/src/_lib/agent-docs-api-render.ts

@@ -0,0 +1,257 @@
+import {
+  type ClassDeclaration,
+  type EnumDeclaration,
+  type FunctionDeclaration,
+  type InterfaceDeclaration,
+  Node,
+  type ParameterDeclaration,
+  type TypeAliasDeclaration,
+  type TypeElementTypes,
+  type TypeNode,
+  type TypeParameterDeclaration,
+  ts,
+  type VariableDeclaration,
+} from "ts-morph";
+import { isInternalApi, isPublicClassMember, jsDocsOf } from "./agent-docs-api-nodes";
+import { firstSentence } from "./agent-docs-shared";
+
+const INDENT = "  ";
+const MAX_INLINE_TYPE_CHARS = 240;
+const MAX_INFERRED_TYPE_CHARS = 120;
+const MAX_NESTED_LITERAL_DEPTH = 3;
+const IMPORT_QUALIFIER_RE = /import\("[^"]*"\)\./g;
+// Readonly modifiers decide nothing for code that passes options in, and they
+// are a tenth of the output.
+const READONLY_MODIFIER_RE = /\breadonly /g;
+
+function collapse(text: string): string {
+  return text
+    .replace(IMPORT_QUALIFIER_RE, "")
+    .replace(READONLY_MODIFIER_RE, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const commentFreePrinter = ts.createPrinter({ removeComments: true });
+
+// Source text keeps line comments, which would swallow the rest of a collapsed
+// one-line signature; the printer re-emits the node without them.
+function nodeText(node: Node): string {
+  const printed = commentFreePrinter.printNode(
+    ts.EmitHint.Unspecified,
+    node.compilerNode,
+    node.getSourceFile().compilerNode,
+  );
+  return collapse(printed);
+}
+
+function capped(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function docSuffix(node: Node): string {
+  const description = jsDocsOf(node).at(-1)?.getDescription().trim() ?? "";
+  return description === "" ? "" : ` // ${firstSentence(description)}`;
+}
+
+function typeParametersText(params: readonly TypeParameterDeclaration[]): string {
+  return params.length === 0 ? "" : `<${params.map((p) => nodeText(p)).join(", ")}>`;
+}
+
+// Destructuring patterns and their defaults are implementation detail; the
+// parameter type already lists the properties.
+function parameterName(param: ParameterDeclaration): string {
+  const nameNode = param.getNameNode();
+  if (Node.isObjectBindingPattern(nameNode)) return "props";
+  if (Node.isArrayBindingPattern(nameNode)) return "args";
+  return nameNode.getText();
+}
+
+function parameterText(param: ParameterDeclaration): string {
+  const rest = param.isRestParameter() ? "..." : "";
+  const optional = param.hasQuestionToken() || param.hasInitializer() ? "?" : "";
+  const typeNode = param.getTypeNode();
+  const typeText = typeNode === undefined ? "" : `: ${nodeText(typeNode)}`;
+  return `${rest}${parameterName(param)}${optional}${typeText}`;
+}
+
+type SignatureLike = {
+  getTypeParameters(): TypeParameterDeclaration[];
+  getParameters(): ParameterDeclaration[];
+  getReturnTypeNode(): TypeNode | undefined;
+  getReturnType(): { getText(enclosing?: Node): string };
+};
+
+function signatureText(signature: SignatureLike & Node): string {
+  const params = signature.getParameters().map(parameterText).join(", ");
+  const declared = signature.getReturnTypeNode();
+  const returnText =
+    declared !== undefined
+      ? nodeText(declared)
+      : inferredText(signature.getReturnType(), signature);
+  return `${typeParametersText(signature.getTypeParameters())}(${params}): ${returnText}`;
+}
+
+function typeText(typeNode: TypeNode | undefined, depth: number, indent: string): string {
+  if (typeNode === undefined) return "unknown";
+  if (Node.isTypeLiteral(typeNode) && depth < MAX_NESTED_LITERAL_DEPTH) {
+    const members = typeNode.getMembers().filter((member) => !isInternalApi(member));
+    if (members.length === 0) return "{}";
+    const lines = members.flatMap((member) => memberLines(member, depth + 1, `${indent}${INDENT}`));
+    return `{\n${lines.join("\n")}\n${indent}}`;
+  }
+  return capped(nodeText(typeNode), MAX_INLINE_TYPE_CHARS);
+}
+
+function memberName(member: TypeElementTypes): string {
+  if (Node.isPropertySignature(member) || Node.isMethodSignature(member)) {
+    const optional = member.hasQuestionToken() ? "?" : "";
+    return `${nodeText(member.getNameNode())}${optional}`;
+  }
+  return "";
+}
+
+function memberLines(member: TypeElementTypes, depth: number, indent: string): string[] {
+  const doc = docSuffix(member);
+  if (Node.isPropertySignature(member)) {
+    const text = typeText(member.getTypeNode(), depth, indent);
+    return [`${indent}${memberName(member)}: ${text};${doc}`];
+  }
+  if (Node.isMethodSignature(member)) {
+    return [`${indent}${memberName(member)}${signatureText(member)};${doc}`];
+  }
+  return [`${indent}${capped(nodeText(member).replace(/;$/, ""), MAX_INLINE_TYPE_CHARS)};${doc}`];
+}
+
+function typeMembersBlock(members: readonly TypeElementTypes[]): string[] {
+  return members
+    .filter((member) => !isInternalApi(member))
+    .flatMap((member) => memberLines(member, 1, INDENT));
+}
+
+function renderInterface(node: InterfaceDeclaration): string[] {
+  const heritage = node.getExtends().map((clause) => nodeText(clause));
+  const extendsText = heritage.length === 0 ? "" : ` extends ${heritage.join(", ")}`;
+  const head = `interface ${node.getName()}${typeParametersText(node.getTypeParameters())}${extendsText}`;
+  const members = typeMembersBlock(node.getMembers());
+  if (members.length === 0) return [`${head} {}${docSuffix(node)}`];
+  return [`${head} {${docSuffix(node)}`, ...members, "}"];
+}
+
+function literalParts(typeNode: TypeNode): { named: string[]; literals: TypeNode[] } {
+  const parts = Node.isIntersectionTypeNode(typeNode) ? typeNode.getTypeNodes() : [typeNode];
+  return {
+    named: parts.filter((part) => !Node.isTypeLiteral(part)).map((part) => nodeText(part)),
+    literals: parts.filter((part) => Node.isTypeLiteral(part)),
+  };
+}
+
+function renderTypeAlias(node: TypeAliasDeclaration): string[] {
+  const head = `type ${node.getName()}${typeParametersText(node.getTypeParameters())} =`;
+  const typeNode = node.getTypeNodeOrThrow();
+  const doc = docSuffix(node);
+  if (Node.isUnionTypeNode(typeNode) && typeNode.getTypeNodes().some(Node.isTypeLiteral)) {
+    const variants = typeNode.getTypeNodes().map((variant) => {
+      const literal = typeText(variant, 1, INDENT);
+      return `${INDENT}| ${Node.isTypeLiteral(variant) ? literal : nodeText(variant)}`;
+    });
+    return [`${head}${doc}`, ...variants, ";"];
+  }
+  const { named, literals } = literalParts(typeNode);
+  if (literals.length === 0) {
+    return [`${head} ${capped(nodeText(typeNode), MAX_INLINE_TYPE_CHARS * 2)};${doc}`];
+  }
+  const members = literals.flatMap((literal) =>
+    Node.isTypeLiteral(literal) ? typeMembersBlock(literal.getMembers()) : [],
+  );
+  const prefix = named.length === 0 ? "" : `${named.join(" & ")} & `;
+  return [`${head} ${prefix}{${doc}`, ...members, "};"];
+}
+
+function renderEnum(node: EnumDeclaration): string[] {
+  const members = node.getMembers().map((member) => nodeText(member));
+  return [`enum ${node.getName()} { ${members.join(", ")} }${docSuffix(node)}`];
+}
+
+function renderClass(node: ClassDeclaration): string[] {
+  const base = node.getExtends();
+  const extendsText = base === undefined ? "" : ` extends ${nodeText(base)}`;
+  const head = `class ${node.getName() ?? "default"}${typeParametersText(node.getTypeParameters())}${extendsText}`;
+  const lines: string[] = [];
+  for (const ctor of node.getConstructors()) {
+    if (isPublicClassMember(ctor)) {
+      lines.push(`${INDENT}constructor(${ctor.getParameters().map(parameterText).join(", ")});`);
+    }
+  }
+  for (const member of node.getMembers()) {
+    if (!isPublicClassMember(member)) continue;
+    const isStatic = Node.isStaticable(member) && member.isStatic() ? "static " : "";
+    if (Node.isPropertyDeclaration(member)) {
+      const text = typeText(member.getTypeNode(), 1, INDENT);
+      lines.push(`${INDENT}${isStatic}${member.getName()}: ${text};${docSuffix(member)}`);
+    } else if (Node.isMethodDeclaration(member)) {
+      lines.push(
+        `${INDENT}${isStatic}${member.getName()}${signatureText(member)};${docSuffix(member)}`,
+      );
+    }
+  }
+  if (lines.length === 0) return [`${head} {}${docSuffix(node)}`];
+  return [`${head} {${docSuffix(node)}`, ...lines, "}"];
+}
+
+function renderFunction(name: string, node: FunctionDeclaration): string[] {
+  const overloads = node.getOverloads();
+  const signatures = overloads.length > 0 ? overloads : [node];
+  return signatures.map(
+    (signature) => `function ${name}${signatureText(signature)};${docSuffix(signature)}`,
+  );
+}
+
+function renderVariable(name: string, node: VariableDeclaration): string[] {
+  const doc = docSuffix(node);
+  const typeNode = node.getTypeNode();
+  if (typeNode !== undefined) return [`const ${name}: ${typeText(typeNode, 1, "")};${doc}`];
+  const initializer = node.getInitializer();
+  if (
+    initializer !== undefined &&
+    (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))
+  ) {
+    return [`function ${name}${signatureText(initializer)};${doc}`];
+  }
+  const inferred = collapse(node.getType().getText(node));
+  if (inferred.length <= MAX_INFERRED_TYPE_CHARS) return [`const ${name}: ${inferred};${doc}`];
+  const keys = objectLiteralKeys(initializer);
+  return [`const ${name}${keys === undefined ? "" : `: { ${keys.join("; ")} }`};${doc}`];
+}
+
+function objectLiteralKeys(initializer: Node | undefined): string[] | undefined {
+  let expression = initializer;
+  while (Node.isAsExpression(expression) || Node.isSatisfiesExpression(expression)) {
+    expression = expression.getExpression();
+  }
+  if (!Node.isObjectLiteralExpression(expression)) return undefined;
+  return expression
+    .getProperties()
+    .flatMap((property) =>
+      Node.isPropertyAssignment(property) ||
+      Node.isShorthandPropertyAssignment(property) ||
+      Node.isMethodDeclaration(property)
+        ? [property.getName()]
+        : [],
+    );
+}
+
+export function renderApiDeclaration(name: string, node: Node): string[] | undefined {
+  if (Node.isFunctionDeclaration(node)) return renderFunction(name, node);
+  if (Node.isVariableDeclaration(node)) return renderVariable(name, node);
+  if (Node.isInterfaceDeclaration(node)) return renderInterface(node);
+  if (Node.isTypeAliasDeclaration(node)) return renderTypeAlias(node);
+  if (Node.isEnumDeclaration(node)) return renderEnum(node);
+  if (Node.isClassDeclaration(node)) return renderClass(node);
+  return undefined;
+}
+
+function inferredText(type: { getText(enclosing?: Node): string }, enclosing: Node): string {
+  const text = collapse(type.getText(enclosing));
+  return text.length <= MAX_INFERRED_TYPE_CHARS ? text : "…";
+}

package/src/_lib/agent-docs-api.ts

@@ -0,0 +1,285 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { Node, type Project, type SourceFile } from "ts-morph";
+import {
+  type ApiTypeDeclaration,
+  isApiTypeDeclaration,
+  isInternalApi,
+  referencedTypeNodes,
+} from "./agent-docs-api-nodes";
+import { renderApiDeclaration } from "./agent-docs-api-render";
+import { compareCodepoint, finishFile, isRecord, parseJsonFile, table } from "./agent-docs-shared";
+
+type ApiEntry = { readonly packageDir: string; readonly subpath: string };
+
+const API_ENTRIES: readonly ApiEntry[] = [
+  { packageDir: "packages/framework", subpath: "./engine" },
+  { packageDir: "packages/framework", subpath: "./errors" },
+  { packageDir: "packages/framework", subpath: "./ui-types" },
+  { packageDir: "packages/framework", subpath: "./db" },
+  { packageDir: "packages/framework", subpath: "./event-store" },
+  { packageDir: "packages/framework", subpath: "./seeding" },
+  { packageDir: "packages/renderer", subpath: "./web" },
+  { packageDir: "packages/testing", subpath: "./stack" },
+  { packageDir: "packages/testing", subpath: "./helpers" },
+  { packageDir: "packages/dev-server", subpath: "./testing" },
+];
+
+// Bundled-feature types stay out of the closure; features.md covers them.
+const TYPES_PACKAGE_DIR = "packages/types";
+const PACKAGE_SCOPE_PREFIX = "@cosmicdrift/kumiko-";
+const TYPES_FILE = "api/types.md";
+
+type ResolvedEntry = {
+  readonly importPath: string;
+  readonly file: string;
+  readonly sourceRel: string;
+  readonly sourceFile: SourceFile;
+};
+
+function resolveEntry(repoRoot: string, project: Project, entry: ApiEntry): ResolvedEntry {
+  const packageJsonRel = `${entry.packageDir}/package.json`;
+  const parsed = parseJsonFile(
+    packageJsonRel,
+    readFileSync(join(repoRoot, packageJsonRel), "utf-8"),
+  );
+  const name = isRecord(parsed) ? parsed["name"] : undefined;
+  const exportsField = isRecord(parsed) ? parsed["exports"] : undefined;
+  const target = isRecord(exportsField) ? exportsField[entry.subpath] : undefined;
+  const typesPath = isRecord(target) ? target["types"] : undefined;
+  if (typeof name !== "string" || typeof typesPath !== "string") {
+    throw new Error(`${packageJsonRel}: needs a name and exports["${entry.subpath}"].types`);
+  }
+  const sourceRel = join(entry.packageDir, typesPath).split(sep).join("/");
+  const slug = `${name.replace(PACKAGE_SCOPE_PREFIX, "")}-${entry.subpath.replace(/^\.\//, "").replace(/\//g, "-")}`;
+  return {
+    importPath: `${name}/${entry.subpath.replace(/^\.\//, "")}`,
+    file: `api/${slug}.md`,
+    sourceRel,
+    sourceFile: project.addSourceFileAtPath(join(repoRoot, sourceRel)),
+  };
+}
+
+// An unresolved `export … from` silently drops its names from
+// getExportedDeclarations(), which would shrink the docs without a signal.
+function assertReExportsResolve(entryFiles: readonly SourceFile[]): void {
+  const pending = [...entryFiles];
+  const visited = new Set<SourceFile>(entryFiles);
+  for (let sourceFile = pending.pop(); sourceFile !== undefined; sourceFile = pending.pop()) {
+    for (const declaration of sourceFile.getExportDeclarations()) {
+      const specifier = declaration.getModuleSpecifierValue();
+      if (specifier === undefined) continue;
+      const target = declaration.getModuleSpecifierSourceFile();
+      if (target === undefined) {
+        throw new Error(`${sourceFile.getFilePath()}: cannot resolve re-export "${specifier}"`);
+      }
+      if (!visited.has(target)) {
+        visited.add(target);
+        pending.push(target);
+      }
+    }
+  }
+}
+
+// The tmp dirs of tests and symlinked checkouts reach the same file under two
+// paths; comparing real paths keeps the closure filter and module headers stable.
+// ts-morph serves the TypeScript lib files from memory, so they have no real path.
+function realFilePath(file: SourceFile): string {
+  const path = file.getFilePath();
+  return existsSync(path) ? realpathSync(path) : path;
+}
+
+type ExportGroup = "Functions" | "Constants" | "Classes" | "Types";
+const EXPORT_GROUP_ORDER: readonly ExportGroup[] = ["Functions", "Constants", "Classes", "Types"];
+
+function exportGroupOf(node: Node): ExportGroup | undefined {
+  if (Node.isFunctionDeclaration(node)) return "Functions";
+  if (Node.isVariableDeclaration(node)) {
+    const initializer = node.getInitializer();
+    const isFunction =
+      node.getTypeNode() === undefined &&
+      initializer !== undefined &&
+      (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer));
+    return isFunction ? "Functions" : "Constants";
+  }
+  if (Node.isEnumDeclaration(node)) return "Constants";
+  if (Node.isClassDeclaration(node)) return "Classes";
+  if (Node.isInterfaceDeclaration(node) || Node.isTypeAliasDeclaration(node)) return "Types";
+  return undefined;
+}
+
+type ExportedApi = { readonly name: string; readonly node: Node; readonly group: ExportGroup };
+
+function publicExportsOf(sourceFile: SourceFile): readonly ExportedApi[] {
+  const found: ExportedApi[] = [];
+  for (const [name, declarations] of sourceFile.getExportedDeclarations()) {
+    for (const node of declarations) {
+      const group = exportGroupOf(node);
+      if (group !== undefined && !isInternalApi(node)) found.push({ name, node, group });
+    }
+  }
+  return found.sort((left, right) => compareCodepoint(left.name, right.name));
+}
+
+function codeBlock(lines: readonly string[]): string {
+  return `\`\`\`ts\n${lines.join("\n")}\n\`\`\``;
+}
+
+function isInsideInternalMember(node: Node): boolean {
+  return node
+    .getAncestors()
+    .some((ancestor) => !isApiTypeDeclaration(ancestor) && isInternalApi(ancestor));
+}
+
+function referencedDeclarations(
+  node: Node,
+  isRepoSource: (file: SourceFile) => boolean,
+): ApiTypeDeclaration[] {
+  const found: ApiTypeDeclaration[] = [];
+  for (const reference of referencedTypeNodes(node)) {
+    if (isInsideInternalMember(reference)) continue;
+    const nameNode = Node.isTypeReference(reference)
+      ? reference.getTypeName()
+      : Node.isExpressionWithTypeArguments(reference)
+        ? reference.getExpression()
+        : undefined;
+    const symbol = nameNode?.getSymbol();
+    const target = symbol?.getAliasedSymbol() ?? symbol;
+    for (const declaration of target?.getDeclarations() ?? []) {
+      if (
+        isApiTypeDeclaration(declaration) &&
+        !isInternalApi(declaration) &&
+        isRepoSource(declaration.getSourceFile())
+      ) {
+        found.push(declaration);
+      }
+    }
+  }
+  return found;
+}
+
+function declarationName(node: ApiTypeDeclaration): string {
+  return node.getName() ?? "default";
+}
+
+export function renderApiDocs(repoRoot: string, project: Project): ReadonlyMap<string, string> {
+  const realRoot = realpathSync(repoRoot);
+  const closureRoots = [
+    ...new Set([...API_ENTRIES.map((entry) => entry.packageDir), TYPES_PACKAGE_DIR]),
+  ].map((packageDir) => `${realRoot}/${packageDir}/`);
+  const isRepoSource = (file: SourceFile): boolean => {
+    const path = realFilePath(file);
+    return closureRoots.some((root) => path.startsWith(root)) && !path.includes("/node_modules/");
+  };
+  const entries = API_ENTRIES.map((entry) => resolveEntry(repoRoot, project, entry));
+  assertReExportsResolve(entries.map((entry) => entry.sourceFile));
+
+  const documentedIn = new Map<Node, string>();
+  const exportsByEntry = entries.map((entry) => publicExportsOf(entry.sourceFile));
+  entries.forEach((entry, index) => {
+    for (const exported of exportsByEntry[index] ?? []) {
+      if (!documentedIn.has(exported.node)) documentedIn.set(exported.node, entry.file);
+    }
+  });
+
+  const files = new Map<string, string>();
+  const pending: Node[] = [];
+  entries.forEach((entry, index) => {
+    const grouped = new Map<ExportGroup, string[]>(EXPORT_GROUP_ORDER.map((group) => [group, []]));
+    const elsewhere = new Map<string, string[]>();
+    for (const exported of exportsByEntry[index] ?? []) {
+      const owner = documentedIn.get(exported.node);
+      if (owner !== entry.file) {
+        const names = elsewhere.get(owner ?? "") ?? [];
+        names.push(`\`${exported.name}\``);
+        elsewhere.set(owner ?? "", names);
+        continue;
+      }
+      grouped
+        .get(exported.group)
+        ?.push(...(renderApiDeclaration(exported.name, exported.node) ?? []));
+      pending.push(exported.node);
+    }
+    const sections = EXPORT_GROUP_ORDER.flatMap((group) => {
+      const lines = grouped.get(group) ?? [];
+      return lines.length === 0 ? [] : [`## ${group}\n\n${codeBlock(lines)}`];
+    });
+    for (const [owner, names] of [...elsewhere].sort(([a], [b]) => compareCodepoint(a, b))) {
+      sections.push(`Also exported here, documented in \`${owner}\`: ${names.join(", ")}`);
+    }
+    const body = `# ${entry.importPath}\n\nImport from \`${entry.importPath}\`. Types used here but not exported by any entry point are in \`${TYPES_FILE}\`.\n\n${sections.join("\n\n")}`;
+    files.set(entry.file, finishFile(entry.sourceRel, body));
+  });
+
+  const referenced = new Set<ApiTypeDeclaration>();
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (node === undefined) break;
+    for (const declaration of referencedDeclarations(node, isRepoSource)) {
+      if (documentedIn.has(declaration) || referenced.has(declaration)) continue;
+      referenced.add(declaration);
+      pending.push(declaration);
+    }
+  }
+  files.set(TYPES_FILE, renderReferencedTypes(repoRoot, referenced));
+  files.set(
+    "api.md",
+    renderApiIndex(
+      entries,
+      exportsByEntry.map((list) => list.length),
+    ),
+  );
+  return files;
+}
+
+function renderReferencedTypes(
+  repoRoot: string,
+  referenced: ReadonlySet<ApiTypeDeclaration>,
+): string {
+  const root = realpathSync(repoRoot);
+  const byModule = new Map<string, ApiTypeDeclaration[]>();
+  for (const declaration of referenced) {
+    const moduleRel = relative(root, realFilePath(declaration.getSourceFile()))
+      .split(sep)
+      .join("/");
+    const list = byModule.get(moduleRel) ?? [];
+    list.push(declaration);
+    byModule.set(moduleRel, list);
+  }
+  const sections = [...byModule]
+    .sort(([left], [right]) => compareCodepoint(left, right))
+    .map(([moduleRel, declarations]) => {
+      const lines = declarations
+        .sort((left, right) => compareCodepoint(declarationName(left), declarationName(right)))
+        .flatMap(
+          (declaration) => renderApiDeclaration(declarationName(declaration), declaration) ?? [],
+        );
+      return `## ${moduleRel}\n\n${codeBlock(lines)}`;
+    });
+  const intro =
+    "Types that appear in the signatures of the entry points but are not exported by any of them. Use them to read option shapes; import only what an entry point exports.";
+  return finishFile(
+    "the API entry points",
+    `# Referenced types\n\n${intro}\n\n${sections.join("\n\n")}`,
+  );
+}
+
+function renderApiIndex(
+  entries: readonly ResolvedEntry[],
+  exportCounts: readonly number[],
+): string {
+  const rows = entries.map((entry, index) => [
+    `\`${entry.importPath}\``,
+    `\`${entry.file}\``,
+    String(exportCounts[index] ?? 0),
+  ]);
+  const intro = [
+    "Public signatures of the entry points an app imports, generated from their sources. Read these instead of `dist/*.d.ts`.",
+    "",
+    "Format: one line per function or constant, object and options types as property lists (`name?: Type;`), and the first sentence of the doc comment after `//`. Bodies and `@internal` declarations are left out. A type that an entry point uses but does not export is listed in `api/types.md`.",
+  ].join("\n");
+  return finishFile(
+    "package.json exports of the listed entry points",
+    `# API reference\n\n${intro}\n\n${table(["Import path", "File", "Exports"], rows)}`,
+  );
+}