@tsplc/compiler 0.0.0-stage → 0.2.0

package/src/frontend/elaborate/index.ts

@@ -0,0 +1,302 @@
+import ts from "typescript";
+import { dirname, join, relative, resolve } from "node:path";
+import { error, type Diagnostic } from "@tsplc/compiler/ir";
+import { runtimeSources } from "../module-graph.ts";
+import { captureGraph } from "./graph.ts";
+import { Model, type Root } from "./model.ts";
+import { setterName, Specializer, SpecializeError } from "./specialize.ts";
+
+/** Directory of the modules elaboration generates, beside the entry module. */
+const generatedDirectory = ".tsplc";
+
+/**
+ * A module the compiled program keeps as written: only types, enums, constants and the service
+ * client. Everything else is plain TypeScript that elaboration compiles from its setup graph.
+ */
+const keptModule = (source: ts.SourceFile, sdk: string): boolean =>
+  source.statements.every((statement) => {
+    if (
+      ts.isImportDeclaration(statement) ||
+      ts.isExportDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    )
+      return true;
+    if (!ts.isVariableStatement(statement)) return false;
+    return statement.declarationList.declarations.every(
+      (declaration) => declaration.initializer && constantInitializer(declaration.initializer, sdk),
+    );
+  });
+
+const constantInitializer = (node: ts.Expression, sdk: string): boolean => {
+  if (
+    ts.isNumericLiteral(node) ||
+    ts.isStringLiteral(node) ||
+    ts.isNoSubstitutionTemplateLiteral(node) ||
+    ts.isBigIntLiteral(node) ||
+    node.kind === ts.SyntaxKind.TrueKeyword ||
+    node.kind === ts.SyntaxKind.FalseKeyword
+  )
+    return true;
+  if (ts.isPrefixUnaryExpression(node)) return constantInitializer(node.operand, sdk);
+  if (
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node) ||
+    ts.isParenthesizedExpression(node)
+  )
+    return constantInitializer(node.expression, sdk);
+  if (ts.isPropertyAccessExpression(node)) return ts.isIdentifier(node.expression);
+  if (ts.isIdentifier(node)) return true;
+  if (ts.isObjectLiteralExpression(node))
+    return node.properties.every(
+      (property) =>
+        (ts.isPropertyAssignment(property) && constantInitializer(property.initializer, sdk)) ||
+        ts.isShorthandPropertyAssignment(property),
+    );
+  if (ts.isArrayLiteralExpression(node))
+    return node.elements.every((element) => constantInitializer(element, sdk));
+  if (ts.isCallExpression(node))
+    return ts.isIdentifier(node.expression) && node.expression.text === "createServiceClient";
+  return false;
+};
+
+/** Whether the program is plain TypeScript: classes with constructors, or setup code building state. */
+const needsElaboration = (sources: readonly ts.SourceFile[], sdk: string): boolean =>
+  sources.some(
+    (source) =>
+      !source.isDeclarationFile &&
+      !source.fileName.startsWith(`${dirname(sdk)}/`) &&
+      !keptModule(source, sdk) &&
+      source.statements.some(
+        (statement) =>
+          ts.isClassDeclaration(statement) &&
+          !statement.heritageClauses?.some((clause) =>
+            clause.types.some((type) => type.expression.getText().startsWith("FunctionBlock")),
+          ),
+      ),
+  );
+
+const importPath = (from: string, to: string): string => {
+  const path = relative(dirname(from), to)
+    .replace(/\\/g, "/")
+    .replace(/\.tsx?$/, "");
+  return path.startsWith("./") || path.startsWith("../") ? path : `./${path}`;
+};
+
+/**
+ * Compiles a plain TypeScript program: runs its setup, then specializes its scan code against
+ * the objects setup built. The result is tsPLC dialect source the rest of the compiler reads.
+ */
+export const lowerElaboration = (
+  program: ts.Program,
+  sdk: string,
+  entries: Readonly<Record<string, { module: string; export: string }>>,
+  root: string,
+): { sources: Map<string, string>; diagnostics: Diagnostic[] } => {
+  const sources = new Map<string, string>();
+  const diagnostics: Diagnostic[] = [];
+  const runtime = runtimeSources(program).filter(
+    (source) => !source.isDeclarationFile && !source.fileName.startsWith(`${dirname(sdk)}/`),
+  );
+  if (!needsElaboration(runtime, sdk)) return { sources, diagnostics };
+  const programEntries = Object.values(entries);
+  if (programEntries.length !== 1)
+    return {
+      sources,
+      diagnostics: [error("PLC1001", "A plain TypeScript program has one entry function.")],
+    };
+  const [entry] = programEntries as [{ module: string; export: string }];
+  const entryFile = resolve(root, entry.module).replace(/\\/g, "/");
+  const entrySource = program.getSourceFile(entryFile);
+  if (!entrySource)
+    return {
+      sources,
+      diagnostics: [error("PLC1001", `${entry.module} is not part of the program.`)],
+    };
+  const checker = program.getTypeChecker();
+  const kept = new Set(
+    runtime.filter((source) => keptModule(source, sdk)).map((source) => source.fileName),
+  );
+  const isKept = (file: string) => kept.has(file);
+  const directory = join(dirname(entryFile), generatedDirectory).replace(/\\/g, "/");
+  const rootModule = (item: Root) => `${directory}/${item.name}.ts`;
+
+  try {
+    const graph = captureGraph(entryFile, runtime);
+    const model = new Model(graph, checker, program, entryFile);
+    const specializer = new Specializer(model, checker, runtime, isKept, rootModule);
+    const main = findEntry(entrySource, entry.export);
+    const body = specializer.entry(main);
+
+    // Exported data the hardware, HMI and server address is stored whether or not code reads it.
+    for (const item of model.roots)
+      if (item.exported && !isKept(item.file) && item.file === entryFile) specializer.use(item);
+
+    const typesFile = `${directory}/types.ts`;
+    const storage = new Map<string, string[]>();
+    for (const item of specializer.roots) {
+      const value = model.rootValues.get(item)!;
+      const node = model.node(value)!;
+      const lines: string[] = [];
+      // Other modules can't assign an imported binding, so each global comes with a setter.
+      const global = (name: string, layout: string, initial: string) =>
+        lines.push(
+          `export let ${name}: ${layout} = ${initial};`,
+          `export function ${setterName(name)}(value: ${layout}): void { ${name} = value; }`,
+        );
+      if (specializer.flattened(item)) {
+        const captured = node.captured;
+        if (captured.kind === "instance") {
+          for (const [name, layout] of specializer.instanceFields(node))
+            global(name, layout, specializer.instanceFieldInitializer(node, name, layout));
+        } else if (captured.kind === "object") {
+          for (const [name, field] of Object.entries(captured.fields)) {
+            const inner = model.node(field);
+            const declared = node.type && model.fieldType(node.type, name, captured);
+            if (!declared) continue;
+            const stored = item.exported || specializer.stored(node, name);
+            if (!stored && !inner) continue;
+            const layout =
+              inner && !item.exported
+                ? specializer.storageType(inner)
+                : specializer.layouts.declaredText(
+                    node.type?.getProperty(name)?.valueDeclaration,
+                    declared,
+                    field,
+                    name.charAt(0).toUpperCase() + name.slice(1),
+                  );
+            if (!layout) continue;
+            global(name, layout, specializer.valueText(field, declared, layout));
+          }
+        }
+      } else {
+        const declared = checker.getTypeAtLocation(item.declaration.name);
+        const layout = specializer.layouts.declaredText(item.declaration, declared, value);
+        global(item.name, layout, specializer.valueText(value, declared, layout));
+      }
+      storage.set(rootModule(item), lines);
+    }
+
+    const typeImports = (file: string) => [
+      ...[...specializer.layouts.imports].map(
+        ([module, names]) =>
+          `import { ${[...names].join(", ")} } from "${importPath(file, module)}";`,
+      ),
+      ...[...specializer.layouts.typeImports].map(
+        ([module, names]) =>
+          `import type { ${[...names].join(", ")} } from "${importPath(file, module)}";`,
+      ),
+    ];
+    const enums = specializer.layouts.enumNames;
+    const interfaces = [...specializer.layouts.declarations.keys()].filter(
+      (name) => !enums.includes(name),
+    );
+    const importTypes = (file: string) => [
+      ...(enums.length
+        ? [`import { ${enums.join(", ")} } from "${importPath(file, typesFile)}";`]
+        : []),
+      ...(interfaces.length
+        ? [`import type { ${interfaces.join(", ")} } from "${importPath(file, typesFile)}";`]
+        : []),
+    ];
+    sources.set(
+      typesFile,
+      [...typeImports(typesFile), ...specializer.layouts.declarations.values()].join("\n"),
+    );
+    for (const [file, lines] of storage)
+      sources.set(file, [...typeImports(file), ...importTypes(file), ...lines].join("\n"));
+
+    const header = [
+      ...typeImports(entryFile),
+      ...importTypes(entryFile),
+      ...[...specializer.namespaces].map(
+        ([name, file]) => `import * as ${name} from "${importPath(entryFile, file)}";`,
+      ),
+      ...[...specializer.imports].map(
+        ([file, names]) =>
+          `import { ${[...names].join(", ")} } from "${importPath(entryFile, file)}";`,
+      ),
+      ...(specializer.sdkImports.size
+        ? [`import { ${[...specializer.sdkImports].join(", ")} } from "@tsplc/compiler/clock";`]
+        : []),
+      ...(specializer.typeImports.size
+        ? [`import { ${[...specializer.typeImports].join(", ")} } from "@tsplc/compiler/types";`]
+        : []),
+    ];
+    sources.set(
+      entryFile,
+      [
+        ...header,
+        ...specializer.tableDeclarations,
+        ...specializer.routines,
+        `export function ${entry.export}(): void {`,
+        ...body,
+        "}",
+      ].join("\n"),
+    );
+    // The plain modules now live in the generated code; keep only their types for type importers.
+    for (const source of runtime)
+      if (source.fileName !== entryFile && !isKept(source.fileName))
+        sources.set(
+          source.fileName,
+          [
+            ...source.statements
+              .filter(
+                (statement) =>
+                  ts.isInterfaceDeclaration(statement) ||
+                  ts.isTypeAliasDeclaration(statement) ||
+                  (ts.isImportDeclaration(statement) && statement.importClause?.isTypeOnly),
+              )
+              .map((statement) => statement.getText()),
+            "export {};",
+          ].join("\n"),
+        );
+  } catch (cause) {
+    if (cause instanceof SpecializeError) {
+      const start = cause.node.getStart();
+      const source = cause.node.getSourceFile();
+      const position = source.getLineAndCharacterOfPosition(start);
+      diagnostics.push(
+        error("PLC1010", cause.message, {
+          file: source.fileName,
+          start,
+          end: cause.node.getEnd(),
+          line: position.line + 1,
+          column: position.character + 1,
+        }),
+      );
+    } else
+      diagnostics.push(
+        error(
+          "PLC1010",
+          cause instanceof Error
+            ? process.env.TSPLC_DEBUG
+              ? String(cause.stack)
+              : cause.message
+            : String(cause),
+        ),
+      );
+  }
+  return { sources, diagnostics };
+};
+
+const findEntry = (
+  source: ts.SourceFile,
+  name: string,
+): ts.FunctionDeclaration | ts.ArrowFunction => {
+  for (const statement of source.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name?.text === name && statement.body)
+      return statement;
+    if (ts.isVariableStatement(statement))
+      for (const declaration of statement.declarationList.declarations)
+        if (
+          ts.isIdentifier(declaration.name) &&
+          declaration.name.text === name &&
+          declaration.initializer &&
+          ts.isArrowFunction(declaration.initializer)
+        )
+          return declaration.initializer;
+  }
+  throw new Error(`${source.fileName} exports no function ${name}.`);
+};

package/src/frontend/elaborate/layouts.ts

@@ -0,0 +1,390 @@
+import ts from "typescript";
+import type { CapturedValue } from "./graph.ts";
+import type { Model } from "./model.ts";
+
+/** IEC names a program can write as types; they keep their width rather than becoming DINT. */
+const iecNames = new Set([
+  "BOOL",
+  "SINT",
+  "INT",
+  "DINT",
+  "LINT",
+  "USINT",
+  "UINT",
+  "UDINT",
+  "ULINT",
+  "BYTE",
+  "WORD",
+  "DWORD",
+  "LWORD",
+  "REAL",
+  "LREAL",
+  "TIME",
+  "DATE",
+  "TIME_OF_DAY",
+  "DATE_AND_TIME",
+]);
+
+/** A union of string literals: a PLC enum. */
+export interface LiteralEnum {
+  name: string;
+  members: string[];
+  /** The union also allows undefined, stored as this extra member. */
+  optional: boolean;
+}
+
+/**
+ * Turns the program's TypeScript types into the PLC dialect's: string-literal unions become enums,
+ * unions of objects become one record tagged by their literal field, `T | undefined` becomes an
+ * optional record, and arrays take their captured length. Declarations it needs collect in `declarations`.
+ */
+export class Layouts {
+  readonly declarations = new Map<string, string>();
+  /** Enums the declarations need from kept modules, by module file. */
+  readonly imports = new Map<string, Set<string>>();
+  /** Types the declarations need from kept modules, by module file. */
+  readonly typeImports = new Map<string, Set<string>>();
+  private readonly enums = new Map<string, LiteralEnum>();
+  private readonly records = new Map<string, string>();
+  private readonly names = new Map<string, number>();
+
+  /** Exported types of kept modules by the type they declare, for types that lost their alias name. */
+  private readonly keptTypes = new Map<ts.Type, { file: string; name: string }>();
+
+  constructor(
+    private readonly model: Model,
+    private readonly checker: ts.TypeChecker,
+    /** Modules the compiled program keeps, whose named types and enums it imports rather than copies. */
+    private readonly kept: (file: string) => boolean,
+    keptSources: readonly ts.SourceFile[] = [],
+  ) {
+    for (const source of keptSources)
+      for (const statement of source.statements)
+        if (
+          (ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) &&
+          isExported(statement)
+        ) {
+          const symbol = checker.getSymbolAtLocation(statement.name);
+          if (symbol)
+            this.keptTypes.set(checker.getDeclaredTypeOfSymbol(symbol), {
+              file: source.fileName,
+              name: statement.name.text,
+            });
+        }
+  }
+
+  private unique(base: string): string {
+    const count = this.names.get(base) ?? 0;
+    this.names.set(base, count + 1);
+    return count ? `${base}_${count + 1}` : base;
+  }
+
+  private import(file: string, name: string, kind: "value" | "type" = "value"): string {
+    const imports = kind === "value" ? this.imports : this.typeImports;
+    const names = imports.get(file) ?? new Set<string>();
+    names.add(name);
+    imports.set(file, names);
+    return name;
+  }
+
+  /** Generated enums, which modules import as values. */
+  get enumNames(): string[] {
+    return [...this.declarations]
+      .filter(([, text]) => text.startsWith("export enum"))
+      .map(([name]) => name);
+  }
+
+  /** The string literals of a union of them, without undefined. */
+  literals(type: ts.Type): { members: string[]; optional: boolean } | undefined {
+    const parts = type.isUnion() ? type.types : [type];
+    const members: string[] = [];
+    let optional = false;
+    for (const part of parts) {
+      if (part.flags & ts.TypeFlags.Undefined) optional = true;
+      else if (part.isStringLiteral()) members.push(part.value);
+      else return undefined;
+    }
+    return members.length ? { members, optional } : undefined;
+  }
+
+  /** The enum a string-literal union compiles to. */
+  literalEnum(type: ts.Type): LiteralEnum | undefined {
+    const literals = this.literals(type);
+    if (!literals) return undefined;
+    const key = [...literals.members].sort().join("|");
+    const existing = this.enums.get(key);
+    if (existing) {
+      existing.optional ||= literals.optional;
+      this.writeEnum(existing);
+      return existing;
+    }
+    const alias = (type.aliasSymbol ?? this.checker.getNonNullableType(type).aliasSymbol)?.name;
+    const declared: LiteralEnum = {
+      name: this.unique(alias ?? pascal(literals.members.join("_or_"))),
+      members: literals.members,
+      optional: literals.optional,
+    };
+    this.enums.set(key, declared);
+    this.writeEnum(declared);
+    return declared;
+  }
+
+  private writeEnum(declared: LiteralEnum): void {
+    const members = [
+      ...(declared.optional ? ["Undefined = 0"] : []),
+      ...declared.members.map((member, index) => `${enumMember(member)} = ${index + 1}`),
+    ];
+    this.declarations.set(declared.name, `export enum ${declared.name} { ${members.join(", ")} }`);
+  }
+
+  /** `Enum.Member` text for a string literal of a literal union. */
+  member(declared: LiteralEnum, value: string | undefined): string {
+    return `${declared.name}.${value === undefined ? "Undefined" : enumMember(value)}`;
+  }
+
+  /** The object types of a union of them, without undefined, when it has a literal tag field. */
+  tagged(type: ts.Type): { tag: string; variants: ts.Type[]; optional: boolean } | undefined {
+    if (!type.isUnion()) return undefined;
+    const variants = type.types.filter((part) => !(part.flags & ts.TypeFlags.Undefined));
+    if (variants.length < 2 || variants.some((part) => !(part.flags & ts.TypeFlags.Object)))
+      return undefined;
+    const first = variants[0]!;
+    for (const property of first.getProperties()) {
+      const literal = (variant: ts.Type) => {
+        const own = variant.getProperty(property.name);
+        const value = own && this.checker.getTypeOfSymbol(own);
+        return value?.isStringLiteral() ? value.value : undefined;
+      };
+      if (variants.every((variant) => literal(variant) !== undefined))
+        return {
+          tag: property.name,
+          variants,
+          optional: variants.length !== type.types.length,
+        };
+    }
+    return undefined;
+  }
+
+  /** The dialect type text for `type`, holding `value` when it was captured. */
+  text(type: ts.Type, value?: CapturedValue, hint?: string): string {
+    const checker = this.checker;
+    const alias = type.aliasSymbol?.name;
+    if (alias && iecNames.has(alias)) return alias;
+    if (type.flags & ts.TypeFlags.BooleanLike) return "boolean";
+    const enumDeclaration = this.enumDeclaration(type);
+    if (enumDeclaration) return this.enumName(enumDeclaration);
+    if (type.flags & ts.TypeFlags.NumberLike) return "number";
+    if (type.flags & ts.TypeFlags.BigIntLike) return "LINT";
+    const literal = this.literalEnum(type);
+    if (literal) return literal.name;
+    const named = this.namedKept(type);
+    if (named) return named;
+    if (type.flags & ts.TypeFlags.StringLike) return "string";
+    const tagged = this.tagged(type);
+    if (tagged) return this.taggedRecord(type, tagged);
+    if (type.isUnion()) {
+      const defined = checker.getNonNullableType(type);
+      if (defined !== type) return this.optional(defined, value);
+    }
+    const element = this.model.elementType(type);
+    if (
+      element &&
+      (checker.isArrayType(type) || checker.isTupleType(type) || isReadonlyArray(type))
+    ) {
+      const node = value && this.model.node(value);
+      if (!node || node.captured.kind !== "array")
+        throw new Error(`${checker.typeToString(type)} needs a length: build it during setup.`);
+      const items = node.captured.items;
+      return `FixedArray<${this.text(element, items[0] ?? this.sample(element))}, ${Math.max(items.length, 1)}>`;
+    }
+    const enumKey = this.enumRecord(type);
+    if (enumKey) return enumKey;
+    if (type.flags & ts.TypeFlags.Object) return this.record(type, value, hint);
+    throw new Error(`${checker.typeToString(type)} has no PLC layout.`);
+  }
+
+  /** The TypeScript enum a type is, or is a union of members of. */
+  enumDeclaration(type: ts.Type): ts.EnumDeclaration | undefined {
+    const parts = type.isUnion() ? type.types : [type];
+    if (!parts.length || !parts.every((part) => part.flags & ts.TypeFlags.EnumLike))
+      return undefined;
+    const symbol = parts[0]!.symbol;
+    const declaration =
+      symbol?.declarations?.find(ts.isEnumDeclaration) ?? symbol?.valueDeclaration?.parent;
+    return declaration && ts.isEnumDeclaration(declaration) ? declaration : undefined;
+  }
+
+  /**
+   * The IEC type a declaration names, such as `WORD`: TypeScript keeps no alias name for an alias
+   * of a primitive, so the width is read from the declaration's annotation.
+   */
+  iecName(declaration: ts.Node | undefined): string | undefined {
+    const node = declaration && (declaration as { type?: ts.TypeNode }).type;
+    return node && ts.isTypeReferenceNode(node) && iecNames.has(node.typeName.getText())
+      ? node.typeName.getText()
+      : undefined;
+  }
+
+  /** A declared field's layout, keeping the IEC widths its annotation names. */
+  declaredText(
+    declaration: ts.Node | undefined,
+    type: ts.Type,
+    value?: CapturedValue,
+    hint?: string,
+  ): string {
+    const iec = this.iecName(declaration);
+    if (iec) return iec;
+    const node = declaration && (declaration as { type?: ts.TypeNode }).type;
+    const element =
+      node && ts.isArrayTypeNode(node)
+        ? node.elementType
+        : node &&
+            ts.isTypeReferenceNode(node) &&
+            ["Array", "ReadonlyArray"].includes(node.typeName.getText())
+          ? node.typeArguments?.[0]
+          : undefined;
+    const elementName =
+      element && ts.isTypeReferenceNode(element) ? element.typeName.getText() : undefined;
+    if (elementName && iecNames.has(elementName)) {
+      const captured = value && this.model.node(value);
+      if (captured?.captured.kind !== "array")
+        throw new Error(
+          `${this.checker.typeToString(type)} needs a length: build it during setup.`,
+        );
+      return `FixedArray<${elementName}, ${Math.max(captured.captured.items.length, 1)}>`;
+    }
+    return this.text(type, value, hint);
+  }
+
+  /** A captured value of a field, from any captured record that has it. */
+  private fieldSample(property: ts.Symbol): CapturedValue | undefined {
+    for (const node of this.model.nodes) {
+      const captured = node.captured;
+      if (
+        (captured.kind === "object" || captured.kind === "instance") &&
+        node.type?.getProperty(property.name) === property
+      )
+        return captured.fields[property.name];
+    }
+    return undefined;
+  }
+
+  /** Some captured value of `type`, giving the lengths of an empty array's element. */
+  private sample(type: ts.Type): CapturedValue | undefined {
+    const node = this.model.nodes.find((candidate) => candidate.type === type);
+    return node && { kind: "node", id: node.id };
+  }
+
+  /** A named type from a module the program keeps, such as a service's procedure record. */
+  private namedKept(type: ts.Type): string | undefined {
+    const declared = this.keptTypes.get(type);
+    if (declared) return this.import(declared.file, declared.name, "type");
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    const declaration = symbol?.declarations?.[0];
+    if (!symbol || !declaration) return undefined;
+    if (!ts.isTypeAliasDeclaration(declaration) && !ts.isInterfaceDeclaration(declaration))
+      return undefined;
+    const file = declaration.getSourceFile().fileName;
+    if (!this.kept(file) || !isExported(declaration)) return undefined;
+    return this.import(file, symbol.name, "type");
+  }
+
+  private enumName(declaration: ts.EnumDeclaration): string {
+    const file = declaration.getSourceFile().fileName;
+    if (!this.kept(file))
+      throw new Error(
+        `${declaration.name.text}: declare PLC enums in a module of enums and constants, so the server and PLC share them.`,
+      );
+    return this.import(file, declaration.name.text);
+  }
+
+  /** `Record<Enum, T>`: an object type whose properties are exactly an enum's members. */
+  private enumRecord(type: ts.Type): string | undefined {
+    const alias = type.aliasSymbol;
+    if (alias?.name !== "Record" || type.aliasTypeArguments?.length !== 2) return undefined;
+    const [key, element] = type.aliasTypeArguments;
+    if (!this.enumDeclaration(key!) && !this.literalEnum(key!)) return undefined;
+    return `Record<${this.text(key!)}, ${this.text(element!, undefined)}>`;
+  }
+
+  /** `{ has, value }` for `T | undefined`. */
+  private optional(defined: ts.Type, value: CapturedValue | undefined): string {
+    const inner = this.text(defined, value?.kind === "undefined" ? undefined : value);
+    const name = `Optional_${inner.replace(/\W+/g, "_")}`;
+    if (!this.declarations.has(name))
+      this.declarations.set(name, `export interface ${name} { has: boolean; value: ${inner}; }`);
+    return name;
+  }
+
+  /** One record for a tagged union: the tag as an enum, and every variant's fields. */
+  private taggedRecord(
+    type: ts.Type,
+    tagged: { tag: string; variants: ts.Type[]; optional: boolean },
+  ): string {
+    const key = `tagged:${this.checker.typeToString(type)}`;
+    const known = this.records.get(key);
+    if (known) return known;
+    const name = this.unique(type.aliasSymbol?.name ?? "Variant");
+    this.records.set(key, name);
+    const tags = tagged.variants.map((variant) => {
+      const property = variant.getProperty(tagged.tag)!;
+      return (this.checker.getTypeOfSymbol(property) as ts.StringLiteralType).value;
+    });
+    const tagEnum: LiteralEnum = { name: `${name}Kind`, members: tags, optional: tagged.optional };
+    this.enums.set([...tags].sort().join("|"), tagEnum);
+    this.writeEnum(tagEnum);
+    const fields = new Map<string, string>();
+    for (const variant of tagged.variants)
+      for (const property of variant.getProperties()) {
+        if (property.name === tagged.tag || fields.has(property.name)) continue;
+        fields.set(
+          property.name,
+          this.declaredText(property.valueDeclaration, this.checker.getTypeOfSymbol(property)),
+        );
+      }
+    this.declarations.set(
+      name,
+      `export interface ${name} { ${tagged.tag}: ${tagEnum.name}; ${[...fields]
+        .map(([field, text]) => `${field}: ${text};`)
+        .join(" ")} }`,
+    );
+    return name;
+  }
+
+  /** A record of an object type; captured arrays inside it can give it distinct variants. */
+  private record(type: ts.Type, value: CapturedValue | undefined, hint?: string): string {
+    const node = value && this.model.node(value);
+    const fields = this.checker.getPropertiesOfType(type).map((property) => {
+      const captured =
+        node && (node.captured.kind === "object" || node.captured.kind === "instance")
+          ? node.captured.fields[property.name]
+          : undefined;
+      return `${property.name}: ${this.declaredText(property.valueDeclaration, this.checker.getTypeOfSymbol(property), captured ?? this.fieldSample(property), pascal(property.name))};`;
+    });
+    const body = fields.join(" ");
+    const base = type.aliasSymbol?.name ?? type.getSymbol()?.name;
+    const key = `${base}:${body}`;
+    const known = this.records.get(key);
+    if (known) return known;
+    const name = this.unique(
+      base && base !== "__type" && base !== "__object" ? base : (hint ?? "Fields"),
+    );
+    this.records.set(key, name);
+    this.declarations.set(name, `export interface ${name} { ${body} }`);
+    return name;
+  }
+}
+
+const isExported = (declaration: ts.Declaration): boolean =>
+  Boolean(ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Export);
+
+const isReadonlyArray = (type: ts.Type): boolean => type.getSymbol()?.name === "ReadonlyArray";
+
+const pascal = (text: string): string =>
+  text.replace(/(^|[^A-Za-z0-9]+)([A-Za-z0-9])/g, (_, __, letter: string) => letter.toUpperCase());
+
+/** A string literal as an enum member name. */
+export const enumMember = (value: string): string => {
+  const name = pascal(value);
+  return /^[A-Za-z_]/.test(name) ? name : `_${name}`;
+};